qdoc: Use '//!' as a documentation comment

This commit makes QDoc treat a string starting with '//!' as a
single-line comment that is not included in the generated HTML
output.

It has several uses: Internal documentation remarks visible only in
the source code, and a simpler alternative to \omit, \endomit commands.
Most importantly, it allows \include command to pull in content from
any file mentioned in the source directories, for example:

  /*!
    \fn foo()

    //! [foo-descr]
    ...long description...
    //! [foo-descr]
  */

  /*/
    \fn foo(int bar)
    \overload foo()
    \include foo.cpp foo-descr
    ...
  */

Above will work and the snippet identifies are omitted from the
generated HTML output.

Change-Id: I0777247dc00358682c307c356fb7d1d8a4514dac
Task-number: QTBUG-52063
Reviewed-by: Martin Smith <martin.smith@theqtcompany.com>

1 files changed, 21 insertions, 14 deletions

diff --git a/src/qdoc/doc/qdoc-manual-markupcmds.qdoc b/src/qdoc/doc/qdoc-manual-markupcmds.qdoc
index 8a682affe..a8d5e6830 100644
--- a/src/qdoc/doc/qdoc-manual-markupcmds.qdoc
+++ b/src/qdoc/doc/qdoc-manual-markupcmds.qdoc
@@ -3775,17 +3775,20 @@
 
     The \\include command sends all or part of the file specified by
     its first argument to the QDoc input stream to be processed as a
-    QDoc comment snippet. This command is often assigned the alias,
-    \e {input}, in the QDoc configuration file, for example \e {alias.include
-    = input}.
-
-    The command is useful when some snippet of commands and text is to
-    be used in multiple places in the documentation. In that case,
-    move the snippet into a separate file and use the \\include
-    command wherever you want to insert the snippet into the
-    documentation. To prevent QDoc from reading the file as a
-    stand-alone page of documentation, we recommend that you use the
-    \c .qdocinc extension for these \e {include} files.
+    QDoc comment snippet.
+
+    The command is useful when some snippet of commands or text is to
+    be used in multiple places in the documentation. Use the \\include
+    command wherever you want to insert a snippet into the documentation.
+    The file containing the snippet to include must be located under the
+    path(s) listed in the \l{sourcedirs-variable}{sourcedirs} QDoc
+    configuration variable. It can be either any source file parsed
+    by QDoc (or even the same one where \\include command is used), or
+    any other text file. To store snippets in a separate file that is
+    not meant to be parsed by QDoc, use a file extension that is not
+    listed in \l {sources.fileextensions-variable}{sources.fileextensions};
+    for example, \c .qdocinc.
+
 
     The command can have either one or two arguments. The first
     argument is always a file name. The contents of the file must be
@@ -3809,7 +3812,7 @@
 
     QDoc renders this page \l{corefeatures.html} {as shown here}.
 
-    \target 2-argument-form}
+    \target 2-argument-form
     \section2 \\include filename snippet-identifier
 
     It is a waste of time to make a separate \c .qdocinc file for every
@@ -3841,8 +3844,12 @@
 
     It works as expected. The sequence of QDoc commands and text found
     between the two tags with the same name as the second argument is
-    sent to the QDoc input stream. You can even nest these snippets,
-    although it's not clear why you would want to do that.
+    sent to the QDoc input stream. You can even have nested snippets.
+
+    \note Snippet identifiers work also within documentation comment
+    (\beginqdoc .. \endqdoc) blocks, so it's not necessary to use a
+    separate \c .qdocinc file. When processing a comment block, QDoc
+    removes any \c {//!} comment lines from the generated output.
 
     \target meta-command
     \section1 \\meta