qdoc: Added 2nd argument to \generate list classes command

The qdoc command \generatelist has an argument that tells
qdoc which list to generate. When the argument is "classes"
qdoc generates the "All C++ Classes" list. qdoc looks for a
common prefix for all the members of the list and sorts the
members of the list using the character that follows the
common prefix. The problem was that the common prefix "Q"
was hardcoded in qdoc.

This update allows the \generate list command to have a
second argument, which is the common prefix. If the common
prefix is not provided, qdoc sorts the members of the list
on the first character.

There is only one use of the \generatelist command with
the classes argument in Qt5. It is changed to be
\generatelist classes Q, and the qdoc user manual is
updated to reflect this change.

Task-number: QTBUG-38226
Change-Id: Ie1011d728819a1e5598bbdf73b7444009377d231
Reviewed-by: Martin Smith <martin.smith@digia.com>

src/tools/qdoc/doc.cpp

@@ -876,7 +876,13 @@ void DocParser::parse(const QString& source,
                     append(Atom::SinceList, getRestOfLine().simplified());
                     break;
                 case CMD_GENERATELIST:
-                    append(Atom::GeneratedList, getArgument());
+                    {
+                        QString arg1 = getArgument();
+                        QString arg2 = getOptionalArgument();
+                        if (!arg2.isEmpty())
+                            arg1 += " " + arg2;
+                        append(Atom::GeneratedList, arg1);
+                    }
                     break;
                 case CMD_GRANULARITY:
                     priv->constructExtra();

src/tools/qdoc/doc/qdoc-manual-markupcmds.qdoc

@@ -3251,9 +3251,9 @@
     \target generatelist-command
     \section1 \\generatelist
 
-    The \\generatelist command expands to a list of various
-    documentation or links to documentation. Below is an example from
-    the Qt Reference Documentation:
+    The \\generatelist command expands to a list of links to the
+    documentation entities in a group. Below is an example from the Qt
+    Reference Documentation:
 
            \code
            / *!
@@ -3263,7 +3263,7 @@
                For a shorter list that only includes the most
                frequently used classes, see \l{Qt's Main Classes}.
 
-               \generatelist classes
+               \generatelist classes Q
            * /
            \endcode
 
@@ -3295,10 +3295,17 @@
     of the class comment's \l {brief-command} {\\brief} command.
 
     \target list example
-    \section2 \c classes
+    \section2 \c {classes <prefix>}
 
     The \c classes argument provides a complete alphabetical list of
-    the classes. Each class name is a link to the class's reference
+    the classes. The second argument, \c{<prefix>}, is the common
+    prefix for the class names. The class names will be sorted on the
+    character that follows the common prefix. e.g. The common prefix
+    for the Qt classes is \c Q. The common prefix argument is
+    optional.  If no common prefix is provided, the class names will
+    be sorted on their first character.
+
+    Each class name becomes a link to the class's reference
     documentation. This command is used to generate the
     \e {All Classes} page this way:
 
@@ -3315,7 +3322,7 @@
         Classes}. For classes that have been deprecated, see the
         \l{Obsolete Classes} list.
 
-        \generatelist classes
+        \generatelist classes Q
     * /
     \endcode
 

src/tools/qdoc/htmlgenerator.cpp

@@ -493,13 +493,16 @@ int HtmlGenerator::generateAtom(const Atom *atom, const Node *relative, CodeMark
             generateAnnotatedList(relative, marker, qdb_->getCppClasses());
         }
         else if (atom->string() == "classes") {
-            generateCompactList(Generic, relative, qdb_->getCppClasses(), true, QStringLiteral("Q"));
+            generateCompactList(Generic, relative, qdb_->getCppClasses(), true, QStringLiteral(""));
+        }
+        else if (atom->string().contains("classes ")) {
+            QString rootName = atom->string().mid(atom->string().indexOf("classes") + 7).trimmed();
+            generateCompactList(Generic, relative, qdb_->getCppClasses(), true, rootName);
         }
         else if (atom->string() == "qmltypes") {
             generateCompactList(Generic, relative, qdb_->getQmlTypes(), true, QStringLiteral(""));
         }
         else if (atom->string().contains("classesbymodule")) {
-            QString arg = atom->string().trimmed();
             QString moduleName = atom->string().mid(atom->string().indexOf("classesbymodule") + 15).trimmed();
             QDocDatabase* qdb = QDocDatabase::qdocDB();
             ModuleNode* mn = qdb->findModule(moduleName);