qdoc: Improve function tagging for grouped \fn commands

QDoc provides a mechanism for tagging specific function declarations
in a header with //! [tag] comments, allowing these tags to be
referenced in an \fn command. This feature did not work for
shared comment nodes containing multiple \fn commands, however.

To make this work, we need to associate the 'bracketed args' (where
the id tag is) with the command itself - previously it was stored
in the Doc instance, but that doesn't work when there are multiple
topic commands sharing a doc. To do so, repurpose the ArgLocPair
structure to store the bracketed arg instead of a Location, as we
never used this particular Location for anything, anyway.

Fixes: QTBUG-95948
Change-Id: Ic899d4252d705f84ba56ea201a55f3e5db068f00
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
(cherry picked from commit 76fb767296e12235d93da683a7f2feb84a7a6675)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>

7 files changed, 33 insertions, 33 deletions

diff --git a/src/qdoc/cppcodeparser.cpp b/src/qdoc/cppcodeparser.cpp
index 26309194e..bf155c520 100644
--- a/src/qdoc/cppcodeparser.cpp
+++ b/src/qdoc/cppcodeparser.cpp
@@ -188,7 +188,7 @@ const QSet<QString> &CppCodeParser::topicCommands()
   Process the topic \a command found in the \a doc with argument \a arg.
  */
 Node *CppCodeParser::processTopicCommand(const Doc &doc, const QString &command,
-                                         const ArgLocPair &arg)
+                                         const ArgPair &arg)
 {
     ExtraFuncData extra;
     if (command == COMMAND_FN) {
@@ -496,9 +496,9 @@ const QSet<QString> &CppCodeParser::metaCommands()
   \a node is guaranteed to be non-null.
  */
 void CppCodeParser::processMetaCommand(const Doc &doc, const QString &command,
-                                       const ArgLocPair &argLocPair, Node *node)
+                                       const ArgPair &argPair, Node *node)
 {
-    QString arg = argLocPair.first;
+    QString arg = argPair.first;
     if (command == COMMAND_INHEADERFILE) {
         if (node->isAggregate())
             static_cast<Aggregate *>(node)->addIncludeFile(arg);
@@ -624,8 +624,8 @@ void CppCodeParser::processMetaCommand(const Doc &doc, const QString &command,
             node->setAbstract(true);
     } else if (command == COMMAND_DEPRECATED) {
         node->setStatus(Node::Deprecated);
-        if (const QString version = doc.bracketedArgs(command); !version.isEmpty())
-            node->setDeprecatedSince(version);
+        if (!argPair.second.isEmpty())
+            node->setDeprecatedSince(argPair.second);
     } else if (command == COMMAND_INGROUP || command == COMMAND_INPUBLICGROUP) {
         // Note: \ingroup and \inpublicgroup are the same (and now recognized as such).
         m_qdb->addToGroup(arg, node);
@@ -915,7 +915,7 @@ void CppCodeParser::processTopicArgs(const Doc &doc, const QString &topic, NodeL
         if (args.size() == 1) {
             if (topic == COMMAND_FN) {
                 if (showInternal() || !doc.isInternal())
-                    node = parserForLanguage("Clang")->parseFnArg(doc.location(), args[0].first, doc.bracketedArgs(topic));
+                    node = parserForLanguage("Clang")->parseFnArg(doc.location(), args[0].first, args[0].second);
             } else if (topic == COMMAND_MACRO) {
                 node = parseMacroArg(doc.location(), args[0].first);
             } else if (isQMLMethodTopic(topic) || isJSMethodTopic(topic)) {
@@ -935,7 +935,7 @@ void CppCodeParser::processTopicArgs(const Doc &doc, const QString &topic, NodeL
                 node = nullptr;
                 if (topic == COMMAND_FN) {
                     if (showInternal() || !doc.isInternal())
-                        node = parserForLanguage("Clang")->parseFnArg(doc.location(), arg.first); // TODO: Ensure \fn commands sharing a comment can have individual bracketed args
+                        node = parserForLanguage("Clang")->parseFnArg(doc.location(), arg.first, arg.second);
                 } else if (topic == COMMAND_MACRO) {
                     node = parseMacroArg(doc.location(), arg.first);
                 } else if (isQMLMethodTopic(topic) || isJSMethodTopic(topic)) {
@@ -958,6 +958,7 @@ void CppCodeParser::processTopicArgs(const Doc &doc, const QString &topic, NodeL
                         nodes.append(scn);
                         docs.append(doc);
                     }
+                    processMetaCommands(doc, node);
                 }
             }
             for (auto *scn : sharedCommentNodes)
diff --git a/src/qdoc/cppcodeparser.h b/src/qdoc/cppcodeparser.h
index 62ace0b91..e14ce9b3d 100644
--- a/src/qdoc/cppcodeparser.h
+++ b/src/qdoc/cppcodeparser.h
@@ -69,11 +69,11 @@ protected:
     static const QSet<QString> &topicCommands();
     static const QSet<QString> &metaCommands();
     virtual Node *processTopicCommand(const Doc &doc, const QString &command,
-                                      const ArgLocPair &arg);
+                                      const ArgPair &arg);
     void processQmlProperties(const Doc &doc, NodeList &nodes, DocList &docs);
     bool splitQmlPropertyArg(const QString &arg, QString &type, QString &module, QString &element,
                              QString &name, const Location &location);
-    void processMetaCommand(const Doc &doc, const QString &command, const ArgLocPair &argLocPair,
+    void processMetaCommand(const Doc &doc, const QString &command, const ArgPair &argLocPair,
                             Node *node);
     void processMetaCommands(const Doc &doc, Node *node);
     void processMetaCommands(NodeList &nodes, DocList &docs);
diff --git a/src/qdoc/doc.cpp b/src/qdoc/doc.cpp
index cff32b4e3..4a4c90357 100644
--- a/src/qdoc/doc.cpp
+++ b/src/qdoc/doc.cpp
@@ -43,6 +43,20 @@ QT_BEGIN_NAMESPACE
 DocUtilities &Doc::m_utilities = DocUtilities::instance();
 
 /*!
+    \typedef ArgList
+    \relates Doc
+
+    A list of metacommand arguments that appear in a Doc. Each entry
+    in the list is a <QString, QString> pair (ArgPair):
+
+    \list
+        \li \c {ArgPair.first} - arguments passed to the command.
+        \li \c {ArgPair.second} - optional argument string passed
+            within brackets immediately following the command.
+    \endlist
+*/
+
+/*!
   Parse the qdoc comment \a source. Build up a list of all the topic
   commands found including their arguments.  This constructor is used
   when there can be more than one topic command in theqdoc comment.
@@ -500,15 +514,4 @@ void Doc::detach()
     m_priv = newPriv;
 }
 
-/*!
-    Returns the argument passed in square brackets to the command \a command,
-    if it exists.
- */
-QString Doc::bracketedArgs(const QString &command) const
-{
-    if (m_priv && m_priv->extra && !m_priv->extra->m_bracketedArgs.isEmpty())
-        return m_priv->extra->m_bracketedArgs[command];
-    return QString();
-}
-
 QT_END_NAMESPACE
diff --git a/src/qdoc/doc.h b/src/qdoc/doc.h
index 3862bdcc8..8008025c7 100644
--- a/src/qdoc/doc.h
+++ b/src/qdoc/doc.h
@@ -46,8 +46,8 @@ class DocPrivate;
 class Quoter;
 class Text;
 
-typedef QPair<QString, Location> ArgLocPair;
-typedef QList<ArgLocPair> ArgList;
+typedef QPair<QString, QString> ArgPair;
+typedef QList<ArgPair> ArgList;
 typedef QMultiMap<QString, QString> QStringMultiMap;
 
 class Doc
@@ -95,7 +95,6 @@ public:
     [[nodiscard]] const QList<Atom *> &keywords() const;
     [[nodiscard]] const QList<Atom *> &targets() const;
     [[nodiscard]] QStringMultiMap *metaTagMap() const;
-    [[nodiscard]] QString bracketedArgs(const QString &command) const;
 
     static void initialize();
     static void terminate();
diff --git a/src/qdoc/docparser.cpp b/src/qdoc/docparser.cpp
index 4a84020f7..814c5fee6 100644
--- a/src/qdoc/docparser.cpp
+++ b/src/qdoc/docparser.cpp
@@ -1101,16 +1101,15 @@ void DocParser::parse(const QString &source, DocPrivate *docPrivate,
                         append(Atom::ParaRight);
                         p1 = getMetaCommandArgument(cmdStr);
                     }
-                    m_private->m_metaCommandMap[cmdStr].append(ArgLocPair(p1, location()));
+                    m_private->m_metaCommandMap[cmdStr].append(ArgPair(p1, QString()));
                     break;
                 case NOT_A_CMD:
                     if (metaCommandSet.contains(cmdStr)) {
                         QString arg;
+                        QString bracketedArg;
                         m_private->m_metacommandsUsed.insert(cmdStr);
-                        if (isLeftBracketAhead()) {
-                            m_private->constructExtra();
-                            m_private->extra->m_bracketedArgs[cmdStr] = getBracketedArgument();
-                        }
+                        if (isLeftBracketAhead())
+                            bracketedArg = getBracketedArgument();
                         // Force a linebreak after \obsolete or \deprecated
                         // to treat potential arguments as a new text paragraph.
                         if (m_position < m_inputLength
@@ -1119,7 +1118,7 @@ void DocParser::parse(const QString &source, DocPrivate *docPrivate,
                             m_input[m_position] = '\n';
                         else
                             arg = getMetaCommandArgument(cmdStr);
-                        m_private->m_metaCommandMap[cmdStr].append(ArgLocPair(arg, location()));
+                        m_private->m_metaCommandMap[cmdStr].append(ArgPair(arg, bracketedArg));
                         if (possibleTopics.contains(cmdStr)) {
                             if (!cmdStr.endsWith(QLatin1String("propertygroup")))
                                 m_private->m_topics.append(Topic(cmdStr, arg));
diff --git a/src/qdoc/docprivate.h b/src/qdoc/docprivate.h
index d3db5219f..edd63a6fe 100644
--- a/src/qdoc/docprivate.h
+++ b/src/qdoc/docprivate.h
@@ -53,7 +53,6 @@
 
 QT_BEGIN_NAMESPACE
 
-typedef QPair<QString, Location> ArgLocPair;
 typedef QMap<QString, ArgList> CommandMap;
 
 struct DocPrivateExtra
@@ -63,7 +62,6 @@ struct DocPrivateExtra
     QList<Atom *> m_keywords {};
     QList<Atom *> m_targets {};
     QStringMultiMap m_metaMap {};
-    QMap<QString, QString> m_bracketedArgs {};
 };
 
 class DocPrivate
diff --git a/src/qdoc/qmlvisitor.cpp b/src/qdoc/qmlvisitor.cpp
index 5f7edde35..9c46ac661 100644
--- a/src/qdoc/qmlvisitor.cpp
+++ b/src/qdoc/qmlvisitor.cpp
@@ -424,8 +424,8 @@ void QmlDocVisitor::applyMetacommands(QQmlJS::SourceLocation, Node *node, Doc &d
                 }
             } else if (command == COMMAND_DEPRECATED) {
                 node->setStatus(Node::Deprecated);
-                if (const QString version = doc.bracketedArgs(command); !version.isEmpty())
-                    node->setDeprecatedSince(version);
+                if (!args[0].second.isEmpty())
+                    node->setDeprecatedSince(args[0].second);
             } else if ((command == COMMAND_INQMLMODULE) || (command == COMMAND_INJSMODULE)) {
                 qdb->addToQmlModule(args[0].first, node);
             } else if (command == COMMAND_QMLINHERITS) {