diff options
author | Topi Reinio <topi.reinio@qt.io> | 2023-03-30 08:34:44 +0000 |
---|---|---|
committer | Topi Reinio <topi.reinio@qt.io> | 2023-04-11 16:16:41 +0000 |
commit | e57bf78334d5b10f23e37d049a58ef24bb5f51e4 (patch) | |
tree | e9af8164f90aa5f2f28a78182d83336428cab9ed | |
parent | a3379894bba777d4dcc8dd6ced5149533bb127ed (diff) | |
download | qttools-e57bf78334d5b10f23e37d049a58ef24bb5f51e4.tar.gz |
Revert "qdoc: Add support for 'category' argument in \generatelist command"
This reverts commit df735050ecd01687f17df8f161c706541319ad05.
While the commit works, it introduces unnecessary complexity to the
processing of the \meta command. The same functionality can be
achieved with the help of a documentation macro.
The commit did contain a bug-fix for the \generatelist command,
which is re-introduced as a separate change.
Pick-to: 6.5
Change-Id: Ie8578baa35cfee210fc52428c610307f51103d22
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
-rw-r--r-- | src/qdoc/cppcodeparser.cpp | 7 | ||||
-rw-r--r-- | src/qdoc/doc/qdoc-manual-markupcmds.qdoc | 31 | ||||
-rw-r--r-- | src/qdoc/docbookgenerator.cpp | 22 | ||||
-rw-r--r-- | src/qdoc/docbookgenerator.h | 5 | ||||
-rw-r--r-- | src/qdoc/docparser.cpp | 10 | ||||
-rw-r--r-- | src/qdoc/htmlgenerator.cpp | 16 | ||||
-rw-r--r-- | src/qdoc/htmlgenerator.h | 2 | ||||
-rw-r--r-- | tests/auto/qdoc/generatedoutput/expected_output/docbook/qmlmodules.xml | 44 | ||||
-rw-r--r-- | tests/auto/qdoc/generatedoutput/expected_output/html/test-componentset-example.webxml | 2 | ||||
-rw-r--r-- | tests/auto/qdoc/generatedoutput/expected_output/qmlmodules.html | 13 | ||||
-rw-r--r-- | tests/auto/qdoc/generatedoutput/testdata/qml/modules.qdoc | 4 | ||||
-rw-r--r-- | tests/auto/qdoc/generatedoutput/tst_generatedoutput.cpp | 1 |
12 files changed, 27 insertions, 130 deletions
diff --git a/src/qdoc/cppcodeparser.cpp b/src/qdoc/cppcodeparser.cpp index 685284c59..9b425114c 100644 --- a/src/qdoc/cppcodeparser.cpp +++ b/src/qdoc/cppcodeparser.cpp @@ -509,11 +509,8 @@ void CppCodeParser::processMetaCommand(const Doc &doc, const QString &command, if (!argPair.second.isEmpty()) node->setDeprecatedSince(argPair.second); } else if (command == COMMAND_INGROUP || command == COMMAND_INPUBLICGROUP) { - // Use bracketed argument as a prefix; used internally by '\meta category' - if (!argPair.second.isEmpty()) - database->addToGroup(argPair.second + " " + arg, node); - else - database->addToGroup(arg, node); + // Note: \ingroup and \inpublicgroup are the same (and now recognized as such). + database->addToGroup(arg, node); } else if (command == COMMAND_INMODULE) { database->addToModule(arg, node); } else if (command == COMMAND_INQMLMODULE) { diff --git a/src/qdoc/doc/qdoc-manual-markupcmds.qdoc b/src/qdoc/doc/qdoc-manual-markupcmds.qdoc index d116a8385..67dc123e7 100644 --- a/src/qdoc/doc/qdoc-manual-markupcmds.qdoc +++ b/src/qdoc/doc/qdoc-manual-markupcmds.qdoc @@ -3356,9 +3356,8 @@ \section1 \\generatelist The \\generatelist command expands to a list of links to the - documentation entities grouped with an \l {ingroup-command} - {\\ingroup} command or entities that match one of the arguments - listed below. An example from the Qt Reference Documentation: + documentation entities in a group. Below is an example from the Qt + Reference Documentation: \badcode * /\1! @@ -3375,11 +3374,6 @@ This generates the \e {All Classes} page. The command accepts the following arguments: - \section2 \c {<group-name>} - - With a group name as the only argument, QDoc lists all entities that - use the \c {\ingroup <group-name>} command. - \target table example \section2 \c annotatedclasses @@ -3549,27 +3543,6 @@ The \c attributions argument is used to tell QDoc to generate a list of attributions in the documentation. - \section2 \c {category <category-name>} - - The \c category argument generates a list of members that use the - \l {meta-command}{\\meta} command to specify a \e category: - - \badcode * - /\1! - \example chat - \meta category {Networking Examples} - \1/ - \endcode - - Use the following \\generatelist command to output a list of - of examples in the \e {Networking Examples} category: - - \badcode - \generatelist category {Networking Examples} - \endcode - - See also \l {meta-command}{\\meta}. - \section2 \c related The \c related argument is used in combination with the \l diff --git a/src/qdoc/docbookgenerator.cpp b/src/qdoc/docbookgenerator.cpp index ceb2fa301..5f370c954 100644 --- a/src/qdoc/docbookgenerator.cpp +++ b/src/qdoc/docbookgenerator.cpp @@ -501,10 +501,7 @@ qsizetype DocBookGenerator::generateAtom(const Atom *atom, const Node *relative) || atom->string() == QLatin1String("related")) { generateList(relative, atom->string()); hasGeneratedSomething = true; // Approximation, because there is - // some nontrivial logic in generateList. - } else if (const auto *cn = m_qdb->getCollectionNode(atom->string(), Node::Group); cn) { - generateAnnotatedList(cn, cn->members(), atom->string(), ItemizedList); - hasGeneratedSomething = true; // Approximation + // some nontrivial logic in generateList. } // There must still be some content generated for the DocBook document @@ -1923,7 +1920,7 @@ void DocBookGenerator::generateList(const Node *relative, const QString &selecto A two-column table is output. */ void DocBookGenerator::generateAnnotatedList(const Node *relative, const NodeList &nodeList, - const QString &selector, GeneratedListType type) + const QString &selector, bool withSectionIfNeeded) { if (nodeList.isEmpty()) return; @@ -1936,14 +1933,13 @@ void DocBookGenerator::generateAnnotatedList(const Node *relative, const NodeLis // Detect if there is a need for a variablelist (i.e. titles mapped to // descriptions) or a regular itemizedlist (only titles). - bool noItemsHaveTitle = - type == ItemizedList || std::all_of(nodeList.begin(), nodeList.end(), - [](const Node* node) { - return node->doc().briefText().toString().isEmpty(); - }); + bool noItemsHaveTitle = std::all_of(nodeList.begin(), nodeList.end(), + [](const Node* node) { + return node->doc().briefText().toString().isEmpty(); + }); // Wrap the list in a section if needed. - if (type == AutoSection && m_hasSection) + if (withSectionIfNeeded && m_hasSection) startSection("", "Contents"); // From WebXMLGenerator::generateAnnotatedList. @@ -1990,7 +1986,7 @@ void DocBookGenerator::generateAnnotatedList(const Node *relative, const NodeLis newLine(); } - if (type == AutoSection && m_hasSection) + if (withSectionIfNeeded && m_hasSection) endSection(); } @@ -5263,7 +5259,7 @@ void DocBookGenerator::generateCollectionNode(CollectionNode *cn) generateAlsoList(cn); if (!cn->noAutoList() && (cn->isGroup() || cn->isQmlModule())) - generateAnnotatedList(cn, cn->members(), "members", AutoSection); + generateAnnotatedList(cn, cn->members(), "members", true); if (generatedTitle) endSection(); diff --git a/src/qdoc/docbookgenerator.h b/src/qdoc/docbookgenerator.h index dfcbcc62c..dce074c03 100644 --- a/src/qdoc/docbookgenerator.h +++ b/src/qdoc/docbookgenerator.h @@ -67,16 +67,13 @@ protected: qsizetype generateAtom(const Atom *atom, const Node *relative) override; private: - - enum GeneratedListType { Auto, AutoSection, ItemizedList }; - QXmlStreamWriter *startDocument(const Node *node); QXmlStreamWriter *startDocument(const ExampleNode *en, const QString &file); QXmlStreamWriter *startGenericDocument(const Node *node, const QString &fileName); void endDocument(); void generateAnnotatedList(const Node *relative, const NodeList &nodeList, - const QString &selector, GeneratedListType type = Auto); + const QString &selector, bool withSectionIfNeeded = false); void generateAnnotatedLists(const Node *relative, const NodeMultiMap &nmm, const QString &selector); void generateCompactList(const Node *relative, const NodeMultiMap &nmm, bool includeAlphabet, diff --git a/src/qdoc/docparser.cpp b/src/qdoc/docparser.cpp index f4a5edb4d..74e9584e8 100644 --- a/src/qdoc/docparser.cpp +++ b/src/qdoc/docparser.cpp @@ -693,15 +693,7 @@ void DocParser::parse(const QString &source, DocPrivate *docPrivate, case CMD_META: m_private->constructExtra(); p1 = getArgument(); - p2 = getArgument(); - m_private->extra->m_metaMap.insert(p1, p2); - // Special case: \meta category adds also a a group 'category<arg>' - if (p1 == QLatin1String("category")) { - QString extraCmd{"ingroup"}; - Q_ASSERT(metaCommandSet.contains(extraCmd)); - m_private->m_metacommandsUsed.insert(extraCmd); - m_private->m_metaCommandMap[extraCmd].append(ArgPair(p2, p1)); - } + m_private->extra->m_metaMap.insert(p1, getArgument()); break; case CMD_NOTE: leavePara(); diff --git a/src/qdoc/htmlgenerator.cpp b/src/qdoc/htmlgenerator.cpp index b2f588275..829950615 100644 --- a/src/qdoc/htmlgenerator.cpp +++ b/src/qdoc/htmlgenerator.cpp @@ -2916,9 +2916,10 @@ void HtmlGenerator::generateQmlItem(const Node *node, const Node *relative, Code } /*! - This function generates a simple unordered list for the members - of collection node \a {cn}. Returns \c true if the list was - generated (collection has members), \c false otherwise. + This function generates a simple bullet list for the members + of collection node \a {cn}. The collection node must be a group + and must not be empty. If it is empty, nothing is output, and + false is returned. Otherewise, the list is generated and true is returned. */ bool HtmlGenerator::generateGroupList(CollectionNode *cn) { @@ -2926,10 +2927,11 @@ bool HtmlGenerator::generateGroupList(CollectionNode *cn) if (cn->members().isEmpty()) return false; out() << "<ul>\n"; - for (const auto *node : cn->members()) { - out() << "<li>"; - generateFullName(node, nullptr); - out() << "</li>\n"; + const auto members = cn->members(); + for (const auto *node : members) { + out() << "<li>" + << "<a href=\"#" << Doc::canonicalTitle(node->title()) << "\">" << node->title() + << "</a></li>\n"; } out() << "</ul>\n"; return true; diff --git a/src/qdoc/htmlgenerator.h b/src/qdoc/htmlgenerator.h index bf5f4de50..3c12ce328 100644 --- a/src/qdoc/htmlgenerator.h +++ b/src/qdoc/htmlgenerator.h @@ -75,7 +75,7 @@ private: bool includeAlphabet, const QString &commonPrefix); void generateFunctionIndex(const Node *relative); void generateLegaleseList(const Node *relative, CodeMarker *marker); - [[nodiscard]] bool generateGroupList(CollectionNode *cn); + bool generateGroupList(CollectionNode *cn); void generateList(const Node *relative, CodeMarker *marker, const QString &selector); void generateSectionList(const Section §ion, const Node *relative, CodeMarker *marker, bool useObsoloteMembers = false); diff --git a/tests/auto/qdoc/generatedoutput/expected_output/docbook/qmlmodules.xml b/tests/auto/qdoc/generatedoutput/expected_output/docbook/qmlmodules.xml deleted file mode 100644 index 3c99e7916..000000000 --- a/tests/auto/qdoc/generatedoutput/expected_output/docbook/qmlmodules.xml +++ /dev/null @@ -1,44 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<db:article xmlns:db="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.2" xml:lang="en"> -<db:info> -<db:title>QML Modules</db:title> -<db:productname>Test</db:productname> -<db:titleabbrev>A test project for QDoc build artifacts</db:titleabbrev> -<db:abstract> -<db:para>A test project for QDoc build artifacts.</db:para></db:abstract> -</db:info> -<db:variablelist role="qml-modules"> -<db:varlistentry> -<db:term><db:link xlink:href="test-empty-qmlmodule.xml" xlink:role="">No QML Types Here</db:link></db:term> -<db:listitem> -<db:para>A QML module with no member types.</db:para> -</db:listitem> -</db:varlistentry> -<db:varlistentry> -<db:term><db:link xlink:href="qdoc-test-qmlmodule.xml" xlink:role="">QDoc.Test QML Module</db:link></db:term> -<db:listitem> -<db:para>QML Types for the Test module.</db:para> -</db:listitem> -</db:varlistentry> -<db:varlistentry> -<db:term><db:link xlink:href="uicomponents-qmlmodule.xml" xlink:role="">UI Components</db:link></db:term> -<db:listitem> -<db:para>Basic set of UI components.</db:para> -</db:listitem> -</db:varlistentry> -<db:varlistentry> -<db:term><db:link xlink:href="test-nover-qmlmodule.xml" xlink:role="">Versionless QML Module</db:link></db:term> -<db:listitem> -<db:para>QML Types for the Test module without version.</db:para> -</db:listitem> -</db:varlistentry> -</db:variablelist> -<db:section xml:id="examples"> -<db:title>Examples</db:title> -<db:variablelist role="category Application Example"> -<db:listitem> -<db:para><db:link xlink:href="test-componentset-example.xml" xlink:role="page">QML Documentation Example</db:link></db:para> -</db:listitem> -</db:variablelist> -</db:section> -</db:article> diff --git a/tests/auto/qdoc/generatedoutput/expected_output/html/test-componentset-example.webxml b/tests/auto/qdoc/generatedoutput/expected_output/html/test-componentset-example.webxml index dc77823e2..600f2f3ed 100644 --- a/tests/auto/qdoc/generatedoutput/expected_output/html/test-componentset-example.webxml +++ b/tests/auto/qdoc/generatedoutput/expected_output/html/test-componentset-example.webxml @@ -1,7 +1,7 @@ <?xml version="1.0" encoding="UTF-8"?> <WebXML> <document> - <page name="componentset" href="test-componentset-example.html" status="active" location="examples.qdoc" documented="true" groups="category Application Example" subtype="example" title="QML Documentation Example" fulltitle="QML Documentation Example" subtitle="" brief="Example for documenting QML types"> + <page name="componentset" href="test-componentset-example.html" status="active" location="examples.qdoc" documented="true" subtype="example" title="QML Documentation Example" fulltitle="QML Documentation Example" subtitle="" brief="Example for documenting QML types"> <contents name="qml-class" title="QML Class" level="1"/> <contents name="properties-signals-handlers-and-methods" title="Properties, Signals, Handlers, and Methods" level="1"/> <contents name="internal-documentation" title="Internal Documentation" level="2"/> diff --git a/tests/auto/qdoc/generatedoutput/expected_output/qmlmodules.html b/tests/auto/qdoc/generatedoutput/expected_output/qmlmodules.html index efc9eebcd..3f1a3e78c 100644 --- a/tests/auto/qdoc/generatedoutput/expected_output/qmlmodules.html +++ b/tests/auto/qdoc/generatedoutput/expected_output/qmlmodules.html @@ -6,14 +6,7 @@ <title>QML Modules | Test</title> </head> <body> -<div class="sidebar"> -<div class="toc"> -<h3 id="toc">Contents</h3> -<ul> -<li class="level1"><a href="#examples">Examples</a></li> -</ul> -</div> -<div class="sidebar-content" id="sidebar-content"></div></div> +<div class="sidebar"><div class="sidebar-content" id="sidebar-content"></div></div> <h1 class="title">QML Modules</h1> <!-- $$$qmlmodules.html-description --> <div class="descr" id="details"> @@ -23,10 +16,6 @@ <tr class="odd topAlign"><td class="tblName" translate="no"><p><a href="uicomponents-qmlmodule.html">UI Components</a></p></td><td class="tblDescr"><p>Basic set of UI components.</p></td></tr> <tr class="even topAlign"><td class="tblName" translate="no"><p><a href="test-nover-qmlmodule.html">Versionless QML Module</a></p></td><td class="tblDescr"><p>QML Types for the Test module without version.</p></td></tr> </table></div> -<h2 id="examples">Examples</h2> -<ul> -<li><a href="test-componentset-example.html">QML Documentation Example</a></li> -</ul> </div> <!-- @@@qmlmodules.html --> </body> diff --git a/tests/auto/qdoc/generatedoutput/testdata/qml/modules.qdoc b/tests/auto/qdoc/generatedoutput/testdata/qml/modules.qdoc index e2177b4f9..f5b7614d9 100644 --- a/tests/auto/qdoc/generatedoutput/testdata/qml/modules.qdoc +++ b/tests/auto/qdoc/generatedoutput/testdata/qml/modules.qdoc @@ -6,8 +6,4 @@ \title QML Modules \generatelist qml-modules - - \section1 Examples - - \generatelist category {Application Example} */ diff --git a/tests/auto/qdoc/generatedoutput/tst_generatedoutput.cpp b/tests/auto/qdoc/generatedoutput/tst_generatedoutput.cpp index 6b48d914d..69d930ff4 100644 --- a/tests/auto/qdoc/generatedoutput/tst_generatedoutput.cpp +++ b/tests/auto/qdoc/generatedoutput/tst_generatedoutput.cpp @@ -321,7 +321,6 @@ void tst_generatedOutput::docBookFromCpp() void tst_generatedOutput::docBookFromQml() { testAndCompare("testdata/configs/docbook_testqml.qdocconf", - "docbook/qmlmodules.xml " "docbook/test-componentset-example.xml " "docbook/uicomponents-qmlmodule.xml " "docbook/qdoc-test-qmlmodule.xml " |