From 2ba87cd00e6527dbd64f5884f29081bd535605bb Mon Sep 17 00:00:00 2001 From: Topi Reinio Date: Thu, 30 Mar 2023 09:09:26 +0000 Subject: qdoc: Fix links in \generatelist output The \generatelist command already supported listing members of a group as a simple unordered list of titles/links, but the links were broken as they always referred to the current document. In DocBook generator, reuse generateAnnotatedList() for this purpose as it already has support for outputting simple itemized/unordered lists. Create a new private enum GeneratedListType to select the list 'subtype' and clean up the API. Add simple test case and documentation of the new argument. Fixes: QTBUG-111575 Pick-to: 6.5 Change-Id: I30e4976cef3b6aa5414aac457844ae5bc0762f3d Reviewed-by: Paul Wicking --- src/qdoc/doc/qdoc-manual-markupcmds.qdoc | 10 ++++++++-- src/qdoc/docbookgenerator.cpp | 22 +++++++++++++--------- src/qdoc/docbookgenerator.h | 5 ++++- src/qdoc/htmlgenerator.cpp | 16 +++++++--------- 4 files changed, 32 insertions(+), 21 deletions(-) (limited to 'src') diff --git a/src/qdoc/doc/qdoc-manual-markupcmds.qdoc b/src/qdoc/doc/qdoc-manual-markupcmds.qdoc index 67dc123e7..04d9f7cc3 100644 --- a/src/qdoc/doc/qdoc-manual-markupcmds.qdoc +++ b/src/qdoc/doc/qdoc-manual-markupcmds.qdoc @@ -3356,8 +3356,9 @@ \section1 \\generatelist 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: + 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: \badcode * /\1! @@ -3374,6 +3375,11 @@ This generates the \e {All Classes} page. The command accepts the following arguments: + \section2 \c {} + + With a group name as the only argument, QDoc lists all entities that + use the \c {\ingroup } command. + \target table example \section2 \c annotatedclasses diff --git a/src/qdoc/docbookgenerator.cpp b/src/qdoc/docbookgenerator.cpp index 5f370c954..ceb2fa301 100644 --- a/src/qdoc/docbookgenerator.cpp +++ b/src/qdoc/docbookgenerator.cpp @@ -501,7 +501,10 @@ 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. + // 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 } // There must still be some content generated for the DocBook document @@ -1920,7 +1923,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, bool withSectionIfNeeded) + const QString &selector, GeneratedListType type) { if (nodeList.isEmpty()) return; @@ -1933,13 +1936,14 @@ 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 = std::all_of(nodeList.begin(), nodeList.end(), - [](const Node* node) { - return node->doc().briefText().toString().isEmpty(); - }); + bool noItemsHaveTitle = + type == ItemizedList || 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 (withSectionIfNeeded && m_hasSection) + if (type == AutoSection && m_hasSection) startSection("", "Contents"); // From WebXMLGenerator::generateAnnotatedList. @@ -1986,7 +1990,7 @@ void DocBookGenerator::generateAnnotatedList(const Node *relative, const NodeLis newLine(); } - if (withSectionIfNeeded && m_hasSection) + if (type == AutoSection && m_hasSection) endSection(); } @@ -5259,7 +5263,7 @@ void DocBookGenerator::generateCollectionNode(CollectionNode *cn) generateAlsoList(cn); if (!cn->noAutoList() && (cn->isGroup() || cn->isQmlModule())) - generateAnnotatedList(cn, cn->members(), "members", true); + generateAnnotatedList(cn, cn->members(), "members", AutoSection); if (generatedTitle) endSection(); diff --git a/src/qdoc/docbookgenerator.h b/src/qdoc/docbookgenerator.h index dce074c03..dfcbcc62c 100644 --- a/src/qdoc/docbookgenerator.h +++ b/src/qdoc/docbookgenerator.h @@ -67,13 +67,16 @@ 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, bool withSectionIfNeeded = false); + const QString &selector, GeneratedListType type = Auto); 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/htmlgenerator.cpp b/src/qdoc/htmlgenerator.cpp index 829950615..e3b91955c 100644 --- a/src/qdoc/htmlgenerator.cpp +++ b/src/qdoc/htmlgenerator.cpp @@ -2916,10 +2916,9 @@ void HtmlGenerator::generateQmlItem(const Node *node, const Node *relative, Code } /*! - 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. + 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. */ bool HtmlGenerator::generateGroupList(CollectionNode *cn) { @@ -2927,11 +2926,10 @@ bool HtmlGenerator::generateGroupList(CollectionNode *cn) if (cn->members().isEmpty()) return false; out() << "
    \n"; - const auto members = cn->members(); - for (const auto *node : members) { - out() << "
  • " - << "title()) << "\">" << node->title() - << "
    • \n"; + for (const auto *node : cn->members()) { + out() << "
  • "; + generateFullName(node, nullptr); + out() << "
    • \n"; } out() << "
\n"; return true; -- cgit v1.2.1