Refactor class Documentation

Replace the map by two fields of string type for detailed/brief and
add accessors. Make the constructor explicit and fix all occurrences
of implicit conversions.

Change QtDocGenerator::writeFormattedText() to take a QString
with the format instead of an instance of Documentation and add
convencience functions writeFormattedBriefText()
and writeFormattedDetailedText().

Change-Id: I4efaecc8cffeff16873fa3926c3f3b731b96bc5b
Reviewed-by: Christian Tismer <tismer@stackless.com>

7 files changed, 88 insertions, 62 deletions

diff --git a/sources/shiboken6/ApiExtractor/documentation.cpp b/sources/shiboken6/ApiExtractor/documentation.cpp
index c042b3b8a..f4c016d97 100644
--- a/sources/shiboken6/ApiExtractor/documentation.cpp
+++ b/sources/shiboken6/ApiExtractor/documentation.cpp
@@ -28,38 +28,29 @@
 
 #include "documentation.h"
 
-Documentation::Documentation(const QString &value, Documentation::Type t, Documentation::Format fmt)
+Documentation::Documentation(const QString &detailed,
+                             const QString &brief,
+                             Format fmt) :
+    m_detailed(detailed.trimmed()), m_brief(brief.trimmed()), m_format(fmt)
 {
-    setValue(value, t, fmt);
 }
 
 bool Documentation::isEmpty() const
 {
-    for (int i = 0; i < Type::Last; i++) {
-        if (!m_data.value(static_cast<Type>(i)).isEmpty())
-            return false;
-    }
-    return true;
+    return m_detailed.isEmpty() && m_brief.isEmpty();
 }
 
-QString Documentation::value(Documentation::Type t) const
+Documentation::Format Documentation::format() const
 {
-    return m_data.value(t);
+    return m_format;
 }
 
-void Documentation::setValue(const QString &value, Documentation::Type t, Documentation::Format fmt)
+void Documentation::setValue(const QString &value, Documentation::Type t)
 {
-    const QString v = value.trimmed();
-    if (v.isEmpty())
-        m_data.remove(t);
+    if (t == Brief)
+        setBrief(value);
     else
-        m_data[t] = value.trimmed();
-    m_format = fmt;
-}
-
-Documentation::Format Documentation::format() const
-{
-    return m_format;
+        setDetailed(value);
 }
 
 void Documentation::setFormat(Documentation::Format f)
@@ -69,5 +60,16 @@ void Documentation::setFormat(Documentation::Format f)
 
 bool Documentation::equals(const Documentation &rhs) const
 {
-    return m_format == rhs.m_format && m_data == rhs.m_data;
+    return m_format == rhs.m_format && m_detailed == rhs.m_detailed
+        && m_brief == rhs.m_brief;
+}
+
+void Documentation::setDetailed(const QString &detailed)
+{
+    m_detailed = detailed.trimmed();
+}
+
+void Documentation::setBrief(const QString &brief)
+{
+    m_brief = brief.trimmed();
 }
diff --git a/sources/shiboken6/ApiExtractor/documentation.h b/sources/shiboken6/ApiExtractor/documentation.h
index 70bfe3292..df2a3fd6f 100644
--- a/sources/shiboken6/ApiExtractor/documentation.h
+++ b/sources/shiboken6/ApiExtractor/documentation.h
@@ -29,16 +29,16 @@
 #ifndef DOCUMENTATION_H
 #define DOCUMENTATION_H
 
-#include <QtCore/QMap>
 #include <QtCore/QString>
 
 class Documentation
 {
 public:
     enum Format {
-        Native,
-        Target
+        Native, // XML
+        Target  // RST
     };
+
     enum Type {
         Detailed,
         Brief,
@@ -46,23 +46,29 @@ public:
     };
 
     Documentation() = default;
-    Documentation(const QString& value, Type t = Documentation::Detailed,
-                  Format fmt = Documentation::Native);
+    explicit Documentation(const QString &detailed,
+                           const QString &brief,
+                           Format fmt = Documentation::Native);
 
     bool isEmpty() const;
-    bool hasBrief() const { return m_data.contains(Brief); }
 
-    QString value(Type t = Documentation::Detailed) const;
-    void setValue(const QString& value, Type t = Documentation::Detailed,
-                  Format fmt = Documentation::Native);
+    void setValue(const QString& value, Type t = Documentation::Detailed);
 
     Documentation::Format format() const;
     void setFormat(Format f);
 
     bool equals(const Documentation &rhs) const;
 
+    const QString &detailed() const { return m_detailed; }
+    void setDetailed(const QString &detailed);
+
+    bool hasBrief() const { return !m_brief.isEmpty(); }
+    const QString &brief() const { return m_brief; }
+    void setBrief(const QString &brief);
+
 private:
-    QMap<Type, QString> m_data;
+    QString m_detailed;
+    QString m_brief;
     Format m_format = Documentation::Native;
 };
 
diff --git a/sources/shiboken6/ApiExtractor/doxygenparser.cpp b/sources/shiboken6/ApiExtractor/doxygenparser.cpp
index a731479c3..90072c227 100644
--- a/sources/shiboken6/ApiExtractor/doxygenparser.cpp
+++ b/sources/shiboken6/ApiExtractor/doxygenparser.cpp
@@ -212,7 +212,7 @@ void DoxygenParser::fillDocumentation(AbstractMetaClass* metaClass)
             qCWarning(lcShibokenDoc, "%s",
                       qPrintable(msgCannotFindDocumentation(doxyFilePath, metaClass, meta_enum, query)));
         }
-        meta_enum.setDocumentation(doc);
+        meta_enum.setDocumentation(Documentation(doc, {}));
     }
 
 }
@@ -237,6 +237,7 @@ Documentation DoxygenParser::retrieveModuleDocumentation(const QString& name){
 
     // Module documentation
     QString query = QLatin1String("/doxygen/compounddef/detaileddescription");
-    return Documentation(getDocumentation(xquery, query, DocModificationList()));
+    const QString doc = getDocumentation(xquery, query, DocModificationList());
+    return Documentation(doc, {});
 }
 
diff --git a/sources/shiboken6/ApiExtractor/qtdocparser.cpp b/sources/shiboken6/ApiExtractor/qtdocparser.cpp
index abd781cb4..9214dc6f4 100644
--- a/sources/shiboken6/ApiExtractor/qtdocparser.cpp
+++ b/sources/shiboken6/ApiExtractor/qtdocparser.cpp
@@ -304,12 +304,13 @@ void QtDocParser::fillDocumentation(AbstractMetaClass* metaClass)
     //Functions Documentation
     const auto &funcs = DocParser::documentableFunctions(metaClass);
     for (const auto &func : funcs) {
-        const QString documentation =
+        const QString detailed =
             queryFunctionDocumentation(sourceFileName, metaClass, classQuery,
                                        func, signedModifs, xquery, &errorMessage);
         if (!errorMessage.isEmpty())
             qCWarning(lcShibokenDoc, "%s", qPrintable(errorMessage));
-        qSharedPointerConstCast<AbstractMetaFunction>(func)->setDocumentation(Documentation(documentation));
+        const Documentation documentation(detailed, {});
+        qSharedPointerConstCast<AbstractMetaFunction>(func)->setDocumentation(documentation);
     }
 #if 0
     // Fields
@@ -376,7 +377,8 @@ Documentation QtDocParser::retrieveModuleDocumentation(const QString& name)
     // Module documentation
     QString query = QLatin1String("/WebXML/document/module[@name=\"")
         + moduleName + QLatin1String("\"]/description");
-    Documentation doc = getDocumentation(xquery, query, DocModificationList());
+    const QString detailed = getDocumentation(xquery, query, DocModificationList());
+    Documentation doc(detailed, {});
     if (doc.isEmpty()) {
         qCWarning(lcShibokenDoc, "%s", qPrintable(msgCannotFindDocumentation(sourceFile, "module", name, query)));
         return doc;
@@ -385,11 +387,11 @@ Documentation QtDocParser::retrieveModuleDocumentation(const QString& name)
     // If a QML module info file exists, insert a link to the Qt docs.
     const QFileInfo qmlModuleFi(prefix + QLatin1String("-qmlmodule.webxml"));
     if (qmlModuleFi.isFile()) {
-        QString docString = doc.value();
+        QString docString = doc.detailed();
         const int pos = docString.lastIndexOf(QLatin1String("</description>"));
         if (pos != -1) {
             docString.insert(pos, qmlReferenceLink(qmlModuleFi));
-            doc.setValue(docString);
+            doc.setDetailed(docString);
         }
     }
 
diff --git a/sources/shiboken6/ApiExtractor/tests/testmodifydocumentation.cpp b/sources/shiboken6/ApiExtractor/tests/testmodifydocumentation.cpp
index 4bf1b8455..521f8d665 100644
--- a/sources/shiboken6/ApiExtractor/tests/testmodifydocumentation.cpp
+++ b/sources/shiboken6/ApiExtractor/tests/testmodifydocumentation.cpp
@@ -75,8 +75,8 @@ R"(<typesystem package="Foo">
     docParser.fillDocumentation(classA);
 
     const Documentation &doc = classA->documentation();
-    const QString actualDocSimplified = doc.value(Documentation::Detailed).simplified();
-    const QString actualBriefSimplified = doc.value(Documentation::Brief).simplified();
+    const QString actualDocSimplified = doc.detailed().simplified();
+    const QString actualBriefSimplified = doc.brief().simplified();
     QVERIFY(!actualDocSimplified.isEmpty());
 
 const char expectedDoc[] =
diff --git a/sources/shiboken6/generator/qtdoc/qtdocgenerator.cpp b/sources/shiboken6/generator/qtdoc/qtdocgenerator.cpp
index 7e8454793..d1de31cef 100644
--- a/sources/shiboken6/generator/qtdoc/qtdocgenerator.cpp
+++ b/sources/shiboken6/generator/qtdoc/qtdocgenerator.cpp
@@ -178,21 +178,32 @@ QString QtDocGenerator::fileNameForContext(const GeneratorContext &context) cons
     return fileNameBase + fileNameSuffix();
 }
 
-void QtDocGenerator::writeFormattedText(TextStream &s, const Documentation &doc,
-                                        const AbstractMetaClass *metaClass,
-                                        Documentation::Type docType) const
+void QtDocGenerator::writeFormattedBriefText(TextStream &s, const Documentation &doc,
+                                             const AbstractMetaClass *metaclass) const
+{
+    writeFormattedText(s, doc.brief(), doc.format(), metaclass);
+}
+
+void QtDocGenerator::writeFormattedDetailedText(TextStream &s, const Documentation &doc,
+                                                const AbstractMetaClass *metaclass) const
+{
+    writeFormattedText(s, doc.detailed(), doc.format(), metaclass);
+}
+
+void QtDocGenerator::writeFormattedText(TextStream &s, const QString &doc,
+                                        Documentation::Format format,
+                                        const AbstractMetaClass *metaClass) const
 {
     QString metaClassName;
 
     if (metaClass)
         metaClassName = metaClass->fullName();
 
-    if (doc.format() == Documentation::Native) {
-        QtXmlToSphinx x(this, m_parameters, doc.value(docType), metaClassName);
+    if (format == Documentation::Native) {
+        QtXmlToSphinx x(this, m_parameters, doc, metaClassName);
         s << x;
     } else {
-        const QString &value = doc.value(docType);
-        const auto lines = QStringView{value}.split(QLatin1Char('\n'));
+        const auto lines = QStringView{doc}.split(QLatin1Char('\n'));
         int typesystemIndentation = std::numeric_limits<int>::max();
         // check how many spaces must be removed from the beginning of each line
         for (const auto &line : lines) {
@@ -251,7 +262,7 @@ void QtDocGenerator::generateClass(TextStream &s, const GeneratorContext &classC
 
     auto documentation = metaClass->documentation();
     if (documentation.hasBrief())
-        writeFormattedText(s, documentation.value(Documentation::Brief), metaClass);
+        writeFormattedBriefText(s, documentation, metaClass);
 
     s << ".. inheritance-diagram:: " << metaClass->fullName()<< '\n'
       << "    :parts: 2\n\n";
@@ -278,7 +289,7 @@ void QtDocGenerator::generateClass(TextStream &s, const GeneratorContext &classC
 
     writeInjectDocumentation(s, TypeSystem::DocModificationPrepend, metaClass, nullptr);
     if (!writeInjectDocumentation(s, TypeSystem::DocModificationReplace, metaClass, nullptr))
-        writeFormattedText(s, documentation.value(Documentation::Detailed), metaClass);
+        writeFormattedDetailedText(s, documentation, metaClass);
 
     if (!metaClass->isNamespace())
         writeConstructors(s, metaClass);
@@ -382,7 +393,7 @@ void QtDocGenerator::writeEnums(TextStream& s, const AbstractMetaClass* cppClass
 
     for (const AbstractMetaEnum &en : cppClass->enums()) {
         s << section_title << cppClass->fullName() << '.' << en.name() << "\n\n";
-        writeFormattedText(s, en.documentation().value(), cppClass);
+        writeFormattedDetailedText(s, en.documentation(), cppClass);
         const auto version = versionOf(en.typeEntry());
         if (!version.isNull())
             s << rstVersionAdded(version);
@@ -396,7 +407,7 @@ void QtDocGenerator::writeFields(TextStream& s, const AbstractMetaClass* cppClas
 
     for (const AbstractMetaField &field : cppClass->fields()) {
         s << section_title << cppClass->fullName() << "." << field.name() << "\n\n";
-        writeFormattedText(s, field.documentation().value(), cppClass);
+        writeFormattedDetailedText(s, field.documentation(), cppClass);
     }
 }
 
@@ -452,7 +463,7 @@ void QtDocGenerator::writeConstructors(TextStream& s, const AbstractMetaClass* c
     s << '\n';
 
     for (const auto &func : qAsConst(lst))
-        writeFormattedText(s, func->documentation().value(), cppClass);
+        writeFormattedDetailedText(s, func->documentation(), cppClass);
 }
 
 QString QtDocGenerator::parseArgDocStyle(const AbstractMetaClass* /* cppClass */,
@@ -577,7 +588,6 @@ bool QtDocGenerator::writeInjectDocumentation(TextStream& s,
             bool modOk = func ? mod.signature() == func->minimalSignature() : mod.signature().isEmpty();
 
             if (modOk) {
-                Documentation doc;
                 Documentation::Format fmt;
 
                 if (mod.format() == TypeSystem::NativeCode)
@@ -587,8 +597,7 @@ bool QtDocGenerator::writeInjectDocumentation(TextStream& s,
                 else
                     continue;
 
-                doc.setValue(mod.code(), Documentation::Detailed, fmt);
-                writeFormattedText(s, doc, cppClass);
+                writeFormattedText(s, mod.code(), fmt, cppClass);
                 didSomething = true;
             }
         }
@@ -738,8 +747,8 @@ void QtDocGenerator::writeFunction(TextStream& s, const AbstractMetaClass* cppCl
     }
     writeInjectDocumentation(s, TypeSystem::DocModificationPrepend, cppClass, func);
     if (!writeInjectDocumentation(s, TypeSystem::DocModificationReplace, cppClass, func)) {
-        writeFormattedText(s, func->documentation(), cppClass, Documentation::Brief);
-        writeFormattedText(s, func->documentation(), cppClass, Documentation::Detailed);
+        writeFormattedBriefText(s, func->documentation(), cppClass);
+        writeFormattedDetailedText(s, func->documentation(), cppClass);
     }
     writeInjectDocumentation(s, TypeSystem::DocModificationAppend, cppClass, func);
 }
@@ -869,10 +878,10 @@ void QtDocGenerator::writeModuleDocumentation()
             if (moduleDoc.format() == Documentation::Native) {
                 QString context = it.key();
                 QtXmlToSphinx::stripPythonQualifiers(&context);
-                QtXmlToSphinx x(this, m_parameters, moduleDoc.value(), context);
+                QtXmlToSphinx x(this, m_parameters, moduleDoc.detailed(), context);
                 s << x;
             } else {
-                s << moduleDoc.value();
+                s << moduleDoc.detailed();
             }
         }
     }
diff --git a/sources/shiboken6/generator/qtdoc/qtdocgenerator.h b/sources/shiboken6/generator/qtdoc/qtdocgenerator.h
index f953a6304..2b18d1edd 100644
--- a/sources/shiboken6/generator/qtdoc/qtdocgenerator.h
+++ b/sources/shiboken6/generator/qtdoc/qtdocgenerator.h
@@ -91,9 +91,15 @@ private:
                             const AbstractMetaArgument &arg) const;
 
     void writeConstructors(TextStream &s, const AbstractMetaClass *cppClass) const;
-    void writeFormattedText(TextStream &s, const Documentation &doc,
-                            const AbstractMetaClass *metaclass = nullptr,
-                            Documentation::Type docType = Documentation::Detailed) const;
+
+    void writeFormattedText(TextStream &s, const QString &doc,
+                            Documentation::Format format,
+                            const AbstractMetaClass *metaClass = nullptr) const;
+    void writeFormattedBriefText(TextStream &s, const Documentation &doc,
+                                 const AbstractMetaClass *metaclass = nullptr) const;
+    void writeFormattedDetailedText(TextStream &s, const Documentation &doc,
+                                    const AbstractMetaClass *metaclass = nullptr) const;
+
     bool writeInjectDocumentation(TextStream& s, TypeSystem::DocModificationMode mode,
                                   const AbstractMetaClass* cppClass,
                                   const AbstractMetaFunctionCPtr &func);