QDoc: Extract method from DocParser::insertTarget

`DocParser::insertTarget` has a conditional check at the start of the
method, that, if satisfied, causes QDoc to generate a warning. The rest
of the method is contained in the else block that follows.

This patch extracts a method, `DocParser::warnAboutPreexistingTarget`,
that is responsible for issuing that warning, and modifies
`DocParser::insertTarget` to return early if the condition is
satisfied. This allows further refactoring of the latter method.
The new method is fully documented. As this new method impacts the
documentation for QDoc warnings, that is also modified in this patch.

Task-number: QTBUG-113126
Change-Id: Iba54e67862555fba71ec774261e0e0fbea638238
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>

2 files changed, 20 insertions, 6 deletions

diff --git a/src/qdoc/qdoc/doc/qdoc-warnings.qdoc b/src/qdoc/qdoc/doc/qdoc-warnings.qdoc
index 0c1ad2cc8..3e08a8e88 100644
--- a/src/qdoc/qdoc/doc/qdoc-warnings.qdoc
+++ b/src/qdoc/qdoc/doc/qdoc-warnings.qdoc
@@ -364,10 +364,11 @@
 
     \section1 Duplicate target name <target>
 
-    This means that there are two \l {target-command}{\\target} commands
-    with the same parameter. They should be unique.
-    This warning is followed by the warning "The previous
-    occurrence is here".
+    This warning is issued if you define two targets with the same parameter,
+    using either the \l {target-command}{\\target} or the \l {keyword-command}
+    {\\keyword} command. The target name given as parameter to these commands
+    must be unique. The warning is followed by "The previous occurrence is
+    here: [location]", where location contains a file name and line number.
 
     \section1 Cannot find qdoc include file <filename>
 
diff --git a/src/qdoc/qdoc/docparser.cpp b/src/qdoc/qdoc/docparser.cpp
index cb6b7788e..ca17fefba 100644
--- a/src/qdoc/qdoc/docparser.cpp
+++ b/src/qdoc/qdoc/docparser.cpp
@@ -1293,11 +1293,24 @@ QString DocParser::detailsUnknownCommand(const QSet<QString> &metaCommandSet, co
     return QStringLiteral("Maybe you meant '\\%1'?").arg(best);
 }
 
+/*!
+    \internal
+
+    Issues a warning about the duplicate definition of a target or keyword in
+    at \a location. \a duplicateDefinition is the target being processed; the
+    already registered definition is \a previousDefinition.
+ */
+static void warnAboutPreexistingTarget(const Location &location, const QString &duplicateDefinition, const QString &previousDefinition)
+{
+    location.warning(
+            QStringLiteral("Duplicate target name '%1'. The previous occurrence is here: %2")
+                    .arg(duplicateDefinition, previousDefinition));
+}
+
 void DocParser::insertTarget(const QString &target, bool keyword)
 {
     if (m_targetMap.contains(target)) {
-        location().warning(QStringLiteral("Duplicate target name '%1'").arg(target));
-        m_targetMap[target].warning(QStringLiteral("(The previous occurrence is here)"));
+        return warnAboutPreexistingTarget(location(), target, m_targetMap[target].toString());
     } else {
         m_targetMap.insert(target, location());
         m_private->constructExtra();