QDoc: Move separator into utilities

Also remove some unused includes where I update includes
in any case.

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

12 files changed, 132 insertions, 131 deletions

diff --git a/src/qdoc/.prev_CMakeLists.txt b/src/qdoc/.prev_CMakeLists.txt
index cab5465fc..cf678f0bf 100644
--- a/src/qdoc/.prev_CMakeLists.txt
+++ b/src/qdoc/.prev_CMakeLists.txt
@@ -61,7 +61,6 @@ qt_internal_add_tool(${target_name}
         quoter.cpp quoter.h
         relatedclass.cpp relatedclass.h
         sections.cpp sections.h
-        separator.cpp separator.h
         sharedcommentnode.cpp sharedcommentnode.h
         singleton.h
         tagfilewriter.cpp tagfilewriter.h
diff --git a/src/qdoc/CMakeLists.txt b/src/qdoc/CMakeLists.txt
index 89b501fc7..4283c448b 100644
--- a/src/qdoc/CMakeLists.txt
+++ b/src/qdoc/CMakeLists.txt
@@ -69,7 +69,6 @@ qt_internal_add_tool(${target_name}
         quoter.cpp quoter.h
         relatedclass.cpp relatedclass.h
         sections.cpp sections.h
-        separator.cpp separator.h
         sharedcommentnode.cpp sharedcommentnode.h
         singleton.h
         tagfilewriter.cpp tagfilewriter.h
diff --git a/src/qdoc/docbookgenerator.cpp b/src/qdoc/docbookgenerator.cpp
index e0fa32cec..a32ce6f76 100644
--- a/src/qdoc/docbookgenerator.cpp
+++ b/src/qdoc/docbookgenerator.cpp
@@ -43,12 +43,10 @@
 #include "quoter.h"
 #include "qdocdatabase.h"
 #include "qmlpropertynode.h"
-#include "separator.h"
 #include "sharedcommentnode.h"
 #include "typedefnode.h"
 #include "variablenode.h"
 
-#include <QtCore/qiterator.h>
 #include <QtCore/qlist.h>
 #include <QtCore/qmap.h>
 #include <QtCore/quuid.h>
@@ -1742,7 +1740,7 @@ void DocBookGenerator::generateSortedNames(const ClassNode *cn, const QList<Rela
     int index = 0;
     for (const QString &className : classNames) {
         generateFullName(classMap.value(className), cn);
-        writer->writeCharacters(comma(index++, classNames.count()));
+        writer->writeCharacters(Utilities::comma(index++, classNames.count()));
     }
 }
 
@@ -1762,7 +1760,7 @@ void DocBookGenerator::generateSortedQmlNames(const Node *base, const NodeList &
 
     for (const QString &name : names) {
         generateFullName(classMap.value(name), base);
-        writer->writeCharacters(comma(index++, names.count()));
+        writer->writeCharacters(Utilities::comma(index++, names.count()));
     }
 }
 
@@ -1830,7 +1828,8 @@ void DocBookGenerator::generateRequisites(const Aggregate *aggregate)
                         writer->writeCharacters(" (protected)");
                     else if ((*r).m_access == Access::Private)
                         writer->writeCharacters(" (private)");
-                    writer->writeCharacters(comma(index++, classe->baseClasses().count()));
+                    writer->writeCharacters(
+                            Utilities::comma(index++, classe->baseClasses().count()));
                 }
                 ++r;
             }
@@ -2890,7 +2889,8 @@ void DocBookGenerator::generateDocBookSynopsis(const Node *node)
                         } else if ((*r).m_access == Access::Private) {
                             writer->writeCharacters(" (private)");
                         }
-                        writer->writeCharacters(comma(index++, classe->baseClasses().count()));
+                        writer->writeCharacters(
+                                Utilities::comma(index++, classe->baseClasses().count()));
                     }
                     ++r;
                 }
diff --git a/src/qdoc/generator.cpp b/src/qdoc/generator.cpp
index 0baa05866..def06df60 100644
--- a/src/qdoc/generator.cpp
+++ b/src/qdoc/generator.cpp
@@ -48,10 +48,10 @@
 #include "qdocdatabase.h"
 #include "qmltypenode.h"
 #include "quoter.h"
-#include "separator.h"
 #include "sharedcommentnode.h"
 #include "tokenizer.h"
 #include "typedefnode.h"
+#include "utilities.h"
 
 #include <QtCore/qdebug.h>
 #include <QtCore/qdir.h>
@@ -138,7 +138,7 @@ void Generator::appendFullNames(Text &text, const NodeList &nodes, const Node *r
     int index = 0;
     for (const auto &node : nodes) {
         appendFullName(text, node, relative);
-        text << comma(index++, nodes.count());
+        text << Utilities::comma(index++, nodes.count());
     }
 }
 
@@ -191,7 +191,7 @@ int Generator::appendSortedNames(Text &text, const ClassNode *cn, const QList<Re
     const QStringList classNames = classMap.keys();
     for (const auto &className : classNames) {
         text << classMap[className];
-        text << comma(index++, classNames.count());
+        text << Utilities::comma(index++, classNames.count());
     }
     return index;
 }
@@ -213,7 +213,7 @@ int Generator::appendSortedQmlNames(Text &text, const Node *base, const NodeList
     const QStringList names = classMap.keys();
     for (const auto &name : names) {
         text << classMap[name];
-        text << comma(index++, names.count());
+        text << Utilities::comma(index++, names.count());
     }
     return index;
 }
@@ -685,7 +685,7 @@ void Generator::generateAlsoList(const Node *node, CodeMarker *marker)
              << Atom(Atom::FormattingRight, ATOM_FORMATTING_BOLD);
 
         for (int i = 0; i < alsoList.size(); ++i)
-            text << alsoList.at(i) << separator(i, alsoList.size());
+            text << alsoList.at(i) << Utilities::separator(i, alsoList.size());
 
         text << Atom::ParaRight;
         generateText(text, node, marker);
@@ -1061,7 +1061,7 @@ void Generator::generateInherits(const ClassNode *classe, CodeMarker *marker)
                 } else if (cls.m_access == Access::Private) {
                     text << " (private)";
                 }
-                text << separator(index++, classe->baseClasses().count());
+                text << Utilities::separator(index++, classe->baseClasses().count());
             }
         }
         text << Atom::ParaRight;
@@ -1181,7 +1181,7 @@ void Generator::generateMaintainerList(const Aggregate *node, CodeMarker *marker
              << "Maintained by: " << Atom(Atom::FormattingRight, ATOM_FORMATTING_BOLD);
 
         for (int i = 0; i < sl.size(); ++i)
-            text << sl.at(i) << separator(i, sl.size());
+            text << sl.at(i) << Utilities::separator(i, sl.size());
 
         text << Atom::ParaRight;
         generateText(text, node, marker);
diff --git a/src/qdoc/htmlgenerator.cpp b/src/qdoc/htmlgenerator.cpp
index 8b75b8fa9..cad722cda 100644
--- a/src/qdoc/htmlgenerator.cpp
+++ b/src/qdoc/htmlgenerator.cpp
@@ -36,7 +36,6 @@
 #include "codemarker.h"
 #include "codeparser.h"
 #include "enumnode.h"
-#include "examplenode.h"
 #include "functionnode.h"
 #include "helpprojectwriter.h"
 #include "manifestwriter.h"
@@ -44,7 +43,6 @@
 #include "propertynode.h"
 #include "qdocdatabase.h"
 #include "qmlpropertynode.h"
-#include "separator.h"
 #include "sharedcommentnode.h"
 #include "tagfilewriter.h"
 #include "tree.h"
@@ -1921,7 +1919,7 @@ void HtmlGenerator::addInheritsToMap(QMap<QString, Text> &requisites, Text *text
                 } else if (cls.m_access == Access::Private) {
                     *text << " (private)";
                 }
-                *text << comma(index++, classe->baseClasses().count());
+                *text << Utilities::comma(index++, classe->baseClasses().count());
             }
         }
         *text << Atom::ParaRight;
diff --git a/src/qdoc/qdoc.pro b/src/qdoc/qdoc.pro
index 6bfbb29e0..b76b6c0f9 100644
--- a/src/qdoc/qdoc.pro
+++ b/src/qdoc/qdoc.pro
@@ -77,7 +77,6 @@ HEADERS += access.h \
            quoter.h \
            relatedclass.h \
            sections.h \
-           separator.h \
            sharedcommentnode.h \
            singleton.h \
            tagfilewriter.h \
@@ -134,7 +133,6 @@ SOURCES += aggregate.cpp \
            quoter.cpp \
            relatedclass.cpp \
            sections.cpp \
-           separator.cpp \
            sharedcommentnode.cpp \
            tagfilewriter.cpp \
            text.cpp \
diff --git a/src/qdoc/separator.cpp b/src/qdoc/separator.cpp
deleted file mode 100644
index 80dc39559..000000000
--- a/src/qdoc/separator.cpp
+++ /dev/null
@@ -1,65 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2019 The Qt Company Ltd.
-** Contact: https://www.qt.io/licensing/
-**
-** This file is part of the tools applications of the Qt Toolkit.
-**
-** $QT_BEGIN_LICENSE:GPL-EXCEPT$
-** Commercial License Usage
-** Licensees holding valid commercial Qt licenses may use this file in
-** accordance with the commercial license agreement provided with the
-** Software or, alternatively, in accordance with the terms contained in
-** a written agreement between you and The Qt Company. For licensing terms
-** and conditions see https://www.qt.io/terms-conditions. For further
-** information use the contact form at https://www.qt.io/contact-us.
-**
-** GNU General Public License Usage
-** Alternatively, this file may be used under the terms of the GNU
-** General Public License version 3 as published by the Free Software
-** Foundation with exceptions as appearing in the file LICENSE.GPL3-EXCEPT
-** included in the packaging of this file. Please review the following
-** information to ensure the GNU General Public License requirements will
-** be met: https://www.gnu.org/licenses/gpl-3.0.html.
-**
-** $QT_END_LICENSE$
-**
-****************************************************************************/
-
-/*
-  separator.cpp
-*/
-
-#include "separator.h"
-
-#include <QtCore/qcoreapplication.h>
-
-QT_BEGIN_NAMESPACE
-
-QString separator(int index, int count)
-{
-    if (index == count - 1)
-        return QCoreApplication::translate("QDoc", ".", "terminator");
-    if (count == 2)
-        return QCoreApplication::translate("QDoc", " and ", "separator when N = 2");
-    if (index == 0)
-        return QCoreApplication::translate("QDoc", ", ", "first separator when N > 2");
-    if (index < count - 2)
-        return QCoreApplication::translate("QDoc", ", ", "general separator when N > 2");
-    return QCoreApplication::translate("QDoc", ", and ", "last separator when N > 2");
-}
-
-QString comma(int index, int count)
-{
-    if (index == count - 1)
-        return QString();
-    if (count == 2)
-        return QCoreApplication::translate("QDoc", " and ", "separator when N = 2");
-    if (index == 0)
-        return QCoreApplication::translate("QDoc", ", ", "first separator when N > 2");
-    if (index < count - 2)
-        return QCoreApplication::translate("QDoc", ", ", "general separator when N > 2");
-    return QCoreApplication::translate("QDoc", ", and ", "last separator when N > 2");
-}
-
-QT_END_NAMESPACE
diff --git a/src/qdoc/separator.h b/src/qdoc/separator.h
deleted file mode 100644
index 69346bd0c..000000000
--- a/src/qdoc/separator.h
+++ /dev/null
@@ -1,45 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2019 The Qt Company Ltd.
-** Contact: https://www.qt.io/licensing/
-**
-** This file is part of the tools applications of the Qt Toolkit.
-**
-** $QT_BEGIN_LICENSE:GPL-EXCEPT$
-** Commercial License Usage
-** Licensees holding valid commercial Qt licenses may use this file in
-** accordance with the commercial license agreement provided with the
-** Software or, alternatively, in accordance with the terms contained in
-** a written agreement between you and The Qt Company. For licensing terms
-** and conditions see https://www.qt.io/terms-conditions. For further
-** information use the contact form at https://www.qt.io/contact-us.
-**
-** GNU General Public License Usage
-** Alternatively, this file may be used under the terms of the GNU
-** General Public License version 3 as published by the Free Software
-** Foundation with exceptions as appearing in the file LICENSE.GPL3-EXCEPT
-** included in the packaging of this file. Please review the following
-** information to ensure the GNU General Public License requirements will
-** be met: https://www.gnu.org/licenses/gpl-3.0.html.
-**
-** $QT_END_LICENSE$
-**
-****************************************************************************/
-
-/*
-  separator.h
-*/
-
-#ifndef SEPARATOR_H
-#define SEPARATOR_H
-
-#include <QtCore/qstring.h>
-
-QT_BEGIN_NAMESPACE
-
-QString separator(int index, int count);
-QString comma(int index, int count);
-
-QT_END_NAMESPACE
-
-#endif
diff --git a/src/qdoc/utilities.cpp b/src/qdoc/utilities.cpp
index e9ef60571..355ceede8 100644
--- a/src/qdoc/utilities.cpp
+++ b/src/qdoc/utilities.cpp
@@ -61,6 +61,47 @@ bool debugging()
 {
     return lcQdoc().isEnabled(QtDebugMsg);
 }
+
+/*!
+    \internal
+    Convenience method that's used to get the correct punctuation character for
+    the words at \a wordPosition in a list of \a numberOfWords length.
+    For the last position in the list, returns "." (full stop). For any other
+    word, this method calls comma().
+
+    \sa comma()
+ */
+QString separator(int wordPosition, int numberOfWords)
+{
+    static QString terminator = QStringLiteral(".");
+    if (wordPosition == numberOfWords - 1)
+        return terminator;
+    else
+        return comma(wordPosition, numberOfWords);
 }
 
+/*!
+    \internal
+    Convenience method that's used to get the correct punctuation character for
+    the words at \a wordPosition in a list of \a numberOfWords length.
+
+    For a list of length one, returns an empty QString. For a list of length
+    two, returns the string " and ". For any length beyond two, returns the
+    string ", " until the last element, which returns ", and ".
+
+    \sa comma()
+ */
+QString comma(int wordPosition, int numberOfWords)
+{
+    if (wordPosition == numberOfWords - 1)
+        return QString();
+    if (numberOfWords == 2)
+        return QStringLiteral(" and ");
+    if (wordPosition == 0 || wordPosition < numberOfWords - 2)
+        return QStringLiteral(", ");
+    return QStringLiteral(", and ");
+}
+
+} // namespace Utilities
+
 QT_END_NAMESPACE
diff --git a/src/qdoc/utilities.h b/src/qdoc/utilities.h
index a30c252a9..705738258 100644
--- a/src/qdoc/utilities.h
+++ b/src/qdoc/utilities.h
@@ -41,6 +41,9 @@ namespace Utilities {
 void startDebugging(const QString &message);
 void stopDebugging(const QString &message);
 bool debugging();
+
+QString separator(int wordPosition, int numberOfWords);
+QString comma(int wordPosition, int numberOfWords);
 };
 
 QT_END_NAMESPACE
diff --git a/src/qdoc/webxmlgenerator.cpp b/src/qdoc/webxmlgenerator.cpp
index 569e51aa5..a5210ae42 100644
--- a/src/qdoc/webxmlgenerator.cpp
+++ b/src/qdoc/webxmlgenerator.cpp
@@ -35,7 +35,6 @@
 #include "node.h"
 #include "propertynode.h"
 #include "qdocdatabase.h"
-#include "separator.h"
 #include "quoter.h"
 
 #include <QtCore/qxmlstream.h>
diff --git a/tests/auto/qdoc/utilities/tst_utilities.cpp b/tests/auto/qdoc/utilities/tst_utilities.cpp
index 322c7197b..2cf19c56c 100644
--- a/tests/auto/qdoc/utilities/tst_utilities.cpp
+++ b/tests/auto/qdoc/utilities/tst_utilities.cpp
@@ -40,6 +40,11 @@ private slots:
     void startDebugging();
     void stopDebugging();
     void debugging();
+    void callSeparatorForOneWord();
+    void callSeparatorForMoreThanOneWord();
+    void callCommaForOneWord();
+    void callCommaForTwoWords();
+    void callCommaForThreeWords();
 };
 
 void tst_Utilities::loggingCategoryName()
@@ -80,6 +85,75 @@ void tst_Utilities::debugging()
     QVERIFY(Utilities::debugging());
 }
 
+void tst_Utilities::callSeparatorForOneWord()
+{
+    const QStringList listOfWords { "one" };
+    const QString expected = QStringLiteral("one.");
+
+    int index = 0;
+    QString result;
+    for (const auto &word : listOfWords) {
+        result.append(word);
+        result.append(Utilities::separator(index++, listOfWords.size()));
+    }
+    QCOMPARE(result, expected);
+}
+
+void tst_Utilities::callSeparatorForMoreThanOneWord()
+{
+    const QStringList listOfWords { "one", "two" };
+    const QString expected = QStringLiteral("one and two.");
+
+    int index = 0;
+    QString result;
+    for (const auto &word : listOfWords) {
+        result.append(word);
+        result.append(Utilities::separator(index++, listOfWords.size()));
+    }
+    QCOMPARE(result, expected);
+}
+
+void tst_Utilities::callCommaForOneWord()
+{
+    const QStringList listOfWords { "one" };
+    const QString expected = QStringLiteral("one");
+
+    int index = 0;
+    QString result;
+    for (const auto &word : listOfWords) {
+        result.append(word);
+        result.append(Utilities::comma(index++, listOfWords.size()));
+    }
+    QCOMPARE(result, expected);
+}
+void tst_Utilities::callCommaForTwoWords()
+{
+    const QStringList listOfWords { "one", "two" };
+    const QString expected = QStringLiteral("one and two");
+
+    int index = 0;
+    QString result;
+    for (const auto &word : listOfWords) {
+        result.append(word);
+        result.append(Utilities::comma(index++, listOfWords.size()));
+    }
+    QCOMPARE(result, expected);
+}
+
+void tst_Utilities::callCommaForThreeWords()
+{
+    const QStringList listOfWords { "one", "two", "three" };
+    const QString expected = QStringLiteral("one, two, and three");
+
+    int index = 0;
+    QString result;
+    for (const auto &word : listOfWords) {
+        result.append(word);
+        result.append(Utilities::comma(index++, listOfWords.size()));
+    }
+    QCOMPARE(result, expected);
+}
+
 QTEST_APPLESS_MAIN(tst_Utilities)
 
 #include "tst_utilities.moc"