Doc: Add a notice about the nomenclature of files generated by QDoc

For many topic commands, QDoc generates a file that represents a page in
the documentation.

QDoc generally generates a filename based on the arguments of the
command and further normalizes the name itself.

This means that the file that is generated might not be named as the
argument in the documentation file itself.

This might be surprising sometimes, especially for commands like
`\page`, where the name is completely inserted by the user and is not
tied to something else in the code.

To try to avoid those surprises and to make it easier for a user to
understand which file will contain the contents that they produced, some
documentation about the nomenclature that QDoc uses for files generated
by the commands was added to the topic commands section of QDoc's
documentation.

Task-number: QTBUG-97174
Change-Id: Iaa6c0c846b88c0d244c0221229ca2b739ab7dbdd
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
(cherry picked from commit 26278e465ad57a0eb0c16ae183bb3efdcb5085f0)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>

1 files changed, 71 insertions, 1 deletions

diff --git a/src/qdoc/doc/qdoc-manual-topiccmds.qdoc b/src/qdoc/doc/qdoc-manual-topiccmds.qdoc
index e0ab113a9..3db7e1cc3 100644
--- a/src/qdoc/doc/qdoc-manual-topiccmds.qdoc
+++ b/src/qdoc/doc/qdoc-manual-topiccmds.qdoc
@@ -93,6 +93,77 @@
     ControllerWindow::setWindowFlags() functions will get the same
     documentation.
 
+    \section2 Nomenclature for files generated by topic commands
+
+    For many topic commands, such as \l {page-command}{\\page}, QDoc
+    generates a file when processing the documentation.
+
+    QDoc normalizes the name of each file before writing it to disk.
+    The following operations are performed:
+
+    \list
+        \li All sequences of non alphanumeric characters are replaced with a hyphen, '-'.
+        \li All uppercase letters are replaced with their lowercase equivalent.
+        \li All trailing hyphens are removed.
+    \endlist
+
+    For example, the following command generates a file named
+    \c{this-generates-a-file-and-writes-it-to-disk.html}:
+
+    \badcode
+    \page this_generates_a_file_(and_writes_it_to_DISK)-.html
+    \endcode
+
+    As the example shows, the name that is given to the file in the
+    command might differ from the name of the actual file that is
+    written to disk.
+
+    \section3 Prefixes and Suffixes for generated files
+
+    When QDoc generates a file, it may add a prefix, a suffix, or both,
+    depending on the element that the file will document.
+
+    The table below shows what those prefixes and suffixes are for
+    various elements.
+
+    \table
+        \header
+            \li Element
+            \li Prefix
+            \li Suffix
+            \li Command
+        \row
+            \li QML Modules
+            \li None
+            \li "-qmlmodule"
+            \li \l {qmlmodule-command}{\\qmlmodule}
+        \row
+            \li Modules
+            \li None
+            \li "-module"
+            \li \l {module-command}{\\module}
+        \row
+            \li Examples
+            \li The project name, as given by the \l
+            {project-variable}{project configuration variable},
+            followed by a hyphen.
+            \li "-example"
+            \li \l {example-command}{\\example}
+        \row
+            \li QML Types
+            \li The output prefix for QML, as given by the \l
+            {outputprefixes-variable}{outputprefixes configuration
+            variable}.
+
+            If the module that contains this type is known to QDoc,
+            the module name is added as a prefix, followed by the QML
+            output suffix, as defined by the \l
+            {outputsuffixes-variable}{outputsuffixes configuration
+            variable} and a hyphen.
+            \li None
+            \li \l {qmltype-command}{\\qmltype}
+    \endtable
+
     \target class-command
     \section1 \\class
 
@@ -1279,7 +1350,6 @@
     the \\qmltype comment should include one or more \l{ingroup-command}
     {\\ingroup} commands.
 
-
     \target qmlproperty-command
     \section1 \\qmlproperty