QDoc: Extract DocParser::insertKeyword from insertTarget

Recent refactoring of `DocParser::insertTarget` exposed that the method
is responsible for the handling of two separate concepts in QDoc, the
commands `\target` and `\keyword`, respectively. Handling of the latter
command was added to the method in question by extending it's signature
with a boolean parameter, whose value was significant in deciding which
code path to follow. However, this API design is no longer considered
appropriate for QDoc, as discussed in review of the previous
refactoring.

This patch extracts the code responsible for inserting keywords into
their related data structure from `DocParser::insertTarget`, and adds
this code to a new member method, `DocParser::insertKeyword`. The
signature of the former method is updated and the relevant call sites
are updated to call the correct method.

The new method is documented as part of its introduction to the code
base. Given that the two methods have striking similarities,
documentation is added to `DocParser::insertTarget` in its new form.

Fixes: QTBUG-113126
Change-Id: Id29bc655c15b6e12726100eb1f33adbf97487236
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>

2 files changed, 47 insertions, 11 deletions

diff --git a/src/qdoc/qdoc/docparser.cpp b/src/qdoc/qdoc/docparser.cpp
index 8ec7a49bf..0d4383f67 100644
--- a/src/qdoc/qdoc/docparser.cpp
+++ b/src/qdoc/qdoc/docparser.cpp
@@ -636,7 +636,7 @@ void DocParser::parse(const QString &source, DocPrivate *docPrivate,
                     break;
                 case CMD_KEYWORD:
                     leavePara();
-                    insertTarget(getRestOfLine(), true);
+                    insertKeyword(getRestOfLine());
                     break;
                 case CMD_L:
                     enterPara();
@@ -955,7 +955,7 @@ void DocParser::parse(const QString &source, DocPrivate *docPrivate,
                     append(Atom::TableOfContents, p1);
                     break;
                 case CMD_TARGET:
-                    insertTarget(getRestOfLine(), false);
+                    insertTarget(getRestOfLine());
                     break;
                 case CMD_TT:
                     startFormat(ATOM_FORMATTING_TELETYPE, cmd);
@@ -1307,7 +1307,21 @@ static void warnAboutPreexistingTarget(const Location &location, const QString &
                     .arg(duplicateDefinition, previousDefinition));
 }
 
-void DocParser::insertTarget(const QString &target, bool keyword)
+/*!
+    \internal
+
+    \brief Registers \a target as a linkable entity.
+
+    The main purpose of this method is to register a target as defined
+    along with its location, so that becomes a valid link target from other
+    parts of the documentation.
+
+    If the \a target name is already registered, a warning is issued,
+    as multiple definitions are problematic.
+
+    \sa insertKeyword, target-command
+ */
+void DocParser::insertTarget(const QString &target)
 {
     if (m_targetMap.contains(target))
         return warnAboutPreexistingTarget(location(), target, m_targetMap[target].toString());
@@ -1315,13 +1329,34 @@ void DocParser::insertTarget(const QString &target, bool keyword)
     m_targetMap.insert(target, location());
     m_private->constructExtra();
 
-    if (keyword) {
-        append(Atom::Keyword, target);
-        m_private->extra->m_keywords.append(m_private->m_text.lastAtom());
-    } else {
-        append(Atom::Target, target);
-        m_private->extra->m_targets.append(m_private->m_text.lastAtom());
-    }
+    append(Atom::Target, target);
+    m_private->extra->m_targets.append(m_private->m_text.lastAtom());
+}
+
+/*!
+    \internal
+
+    \brief Registers \a keyword as a linkable entity.
+
+    The main purpose of this method is to register a keyword as defined
+    along with its location, so that becomes a valid link target from other
+    parts of the documentation.
+
+    If the \a keyword name is already registered, a warning is issued,
+    as multiple definitions are problematic.
+
+    \sa insertTarget, keyword-command
+ */
+void DocParser::insertKeyword(const QString &keyword)
+{
+    if (m_targetMap.contains(keyword))
+        return warnAboutPreexistingTarget(location(), keyword, m_targetMap[keyword].toString());
+
+    m_targetMap.insert(keyword, location());
+    m_private->constructExtra();
+
+    append(Atom::Keyword, keyword);
+    m_private->extra->m_keywords.append(m_private->m_text.lastAtom());
 }
 
 void DocParser::include(const QString &fileName, const QString &identifier, const QStringList &parameters)
diff --git a/src/qdoc/qdoc/docparser.h b/src/qdoc/qdoc/docparser.h
index bed6608f8..4b5d75160 100644
--- a/src/qdoc/qdoc/docparser.h
+++ b/src/qdoc/qdoc/docparser.h
@@ -46,7 +46,8 @@ public:
 private:
     Location &location();
     QString detailsUnknownCommand(const QSet<QString> &metaCommandSet, const QString &str);
-    void insertTarget(const QString &target, bool keyword);
+    void insertTarget(const QString &target);
+    void insertKeyword(const QString &keyword);
     void include(const QString &fileName, const QString &identifier, const QStringList &parameters);
     void startFormat(const QString &format, int cmd);
     bool openCommand(int cmd);