shiboken6: Refactor handling of the brief class documentation

Move the extraction of the brief text from the
QtDocGenerator to the QtDocParser and store the  brief text
in class Documentation, allowing for later extraction.
The handling for qdoc and doxygen should then be consistent.

Change-Id: I86b37ae1c4a92f96508a03f5dbcfb6dc56014382
Reviewed-by: Cristian Maureira-Fredes <cristian.maureira-fredes@qt.io>
Reviewed-by: Christian Tismer <tismer@stackless.com>
(cherry picked from commit 1c4b7ddb0f879909f5d2f9f6207c06dfd2493340)

4 files changed, 41 insertions, 34 deletions

diff --git a/sources/shiboken2/ApiExtractor/abstractmetalang.h b/sources/shiboken2/ApiExtractor/abstractmetalang.h
index 9d0facd7d..92c9189b8 100644
--- a/sources/shiboken2/ApiExtractor/abstractmetalang.h
+++ b/sources/shiboken2/ApiExtractor/abstractmetalang.h
@@ -77,6 +77,7 @@ public:
                   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,
diff --git a/sources/shiboken2/ApiExtractor/qtdocparser.cpp b/sources/shiboken2/ApiExtractor/qtdocparser.cpp
index 0550e13d3..4c119cb06 100644
--- a/sources/shiboken2/ApiExtractor/qtdocparser.cpp
+++ b/sources/shiboken2/ApiExtractor/qtdocparser.cpp
@@ -34,6 +34,9 @@
 #include <QtCore/QXmlStreamReader>
 #include <QUrl>
 
+static inline QString briefStartElement() { return QStringLiteral("<brief>"); }
+static inline QString briefEndElement() { return QStringLiteral("</brief>"); }
+
 Documentation QtDocParser::retrieveModuleDocumentation()
 {
     return retrieveModuleDocumentation(packageName());
@@ -199,6 +202,25 @@ QString QtDocParser::queryFunctionDocumentation(const QString &sourceFileName,
     return result;
 }
 
+// Extract the <brief> section from a WebXML (class) documentation and remove it
+// from the source.
+static QString extractBrief(QString *value)
+{
+    const auto briefStart = value->indexOf(briefStartElement());
+    if (briefStart < 0)
+        return {};
+    const auto briefEnd = value->indexOf(briefEndElement(),
+                                         briefStart + briefStartElement().size());
+    if (briefEnd < briefStart)
+        return {};
+    const auto briefLength = briefEnd + briefEndElement().size() - briefStart;
+    QString briefValue = value->mid(briefStart, briefLength);
+    briefValue.insert(briefValue.size() - briefEndElement().size(),
+                      QLatin1String("<rst> More_...</rst>"));
+    value->remove(briefStart, briefLength);
+    return briefValue;
+}
+
 void QtDocParser::fillDocumentation(AbstractMetaClass* metaClass)
 {
     if (!metaClass)
@@ -250,9 +272,17 @@ void QtDocParser::fillDocumentation(AbstractMetaClass* metaClass)
             signedModifs.append(docModif);
     }
 
-    Documentation doc(getDocumentation(xquery, query, classModifs));
-    if (doc.isEmpty())
-         qCWarning(lcShibokenDoc, "%s", qPrintable(msgCannotFindDocumentation(sourceFileName, "class", className, query)));
+    QString docString = getDocumentation(xquery, query, classModifs);
+    if (docString.isEmpty()) {
+        qCWarning(lcShibokenDoc, "%s",
+                  qPrintable(msgCannotFindDocumentation(sourceFileName, "class", className, query)));
+    }
+    const QString brief = extractBrief(&docString);
+
+    Documentation doc;
+    if (!brief.isEmpty())
+        doc.setValue(brief, Documentation::Brief);
+    doc.setValue(docString);
     metaClass->setDocumentation(doc);
 
     //Functions Documentation
diff --git a/sources/shiboken2/ApiExtractor/tests/testmodifydocumentation.cpp b/sources/shiboken2/ApiExtractor/tests/testmodifydocumentation.cpp
index 6acac41d5..cf3982a18 100644
--- a/sources/shiboken2/ApiExtractor/tests/testmodifydocumentation.cpp
+++ b/sources/shiboken2/ApiExtractor/tests/testmodifydocumentation.cpp
@@ -72,13 +72,14 @@ R"(<typesystem package="Foo">
     docParser.setDocumentationDataDirectory(tempDir.path());
     docParser.fillDocumentation(classA);
 
-    const QString actualDocSimplified = classA->documentation().value().simplified();
+    const Documentation &doc = classA->documentation();
+    const QString actualDocSimplified = doc.value(Documentation::Detailed).simplified();
+    const QString actualBriefSimplified = doc.value(Documentation::Brief).simplified();
     QVERIFY(!actualDocSimplified.isEmpty());
 
 const char expectedDoc[] =
 R"(<?xml version="1.0"?>
 <description>oi
-<brief>Modified Brief</brief>
 <para>Paragraph number 1</para>
 <para>Paragraph number 2</para>
 <para>Some changed contents here</para>
@@ -86,7 +87,7 @@ R"(<?xml version="1.0"?>
 )";
     const QString expectedDocSimplified = QString::fromLatin1(expectedDoc).simplified();
     // Check whether the first modification worked.
-    QVERIFY(actualDocSimplified.contains(QLatin1String("Modified Brief")));
+    QVERIFY(actualBriefSimplified.contains(QLatin1String("Modified Brief")));
 
 #ifndef HAVE_LIBXSLT
     // QtXmlPatterns is unable to handle para[3] in style sheets,
diff --git a/sources/shiboken2/generator/qtdoc/qtdocgenerator.cpp b/sources/shiboken2/generator/qtdoc/qtdocgenerator.cpp
index 40af0958d..784cdfbf2 100644
--- a/sources/shiboken2/generator/qtdoc/qtdocgenerator.cpp
+++ b/sources/shiboken2/generator/qtdoc/qtdocgenerator.cpp
@@ -1581,30 +1581,6 @@ static void writeInheritedByList(QTextStream& s, const AbstractMetaClass* metaCl
     s << classes.join(QLatin1String(", ")) << Qt::endl << Qt::endl;
 }
 
-// Extract the <brief> section from a WebXML (class) documentation and remove it
-// from the source.
-static bool extractBrief(Documentation *sourceDoc, Documentation *brief)
-{
-    if (sourceDoc->format() != Documentation::Native)
-        return false;
-    QString value = sourceDoc->value();
-    const int briefStart = value.indexOf(briefStartElement());
-    if (briefStart < 0)
-        return false;
-    const int briefEnd = value.indexOf(briefEndElement(), briefStart + briefStartElement().size());
-    if (briefEnd < briefStart)
-        return false;
-    const int briefLength = briefEnd + briefEndElement().size() - briefStart;
-    brief->setFormat(Documentation::Native);
-    QString briefValue = value.mid(briefStart, briefLength);
-    briefValue.insert(briefValue.size() - briefEndElement().size(),
-                      QLatin1String("<rst> More_...</rst>"));
-    brief->setValue(briefValue);
-    value.remove(briefStart, briefLength);
-    sourceDoc->setValue(value);
-    return true;
-}
-
 void QtDocGenerator::generateClass(QTextStream &s, const GeneratorContext &classContext)
 {
     const AbstractMetaClass *metaClass = classContext.metaClass();
@@ -1623,9 +1599,8 @@ void QtDocGenerator::generateClass(QTextStream &s, const GeneratorContext &class
     s << Pad('*', className.count()) << Qt::endl << Qt::endl;
 
     auto documentation = metaClass->documentation();
-    Documentation brief;
-    if (extractBrief(&documentation, &brief))
-        writeFormattedText(s, brief.value(), metaClass);
+    if (documentation.hasBrief())
+        writeFormattedText(s, documentation.value(Documentation::Brief), metaClass);
 
     s << ".. inheritance-diagram:: " << metaClass->fullName() << Qt::endl
       << "    :parts: 2" << Qt::endl << Qt::endl;
@@ -1652,7 +1627,7 @@ void QtDocGenerator::generateClass(QTextStream &s, const GeneratorContext &class
 
     writeInjectDocumentation(s, TypeSystem::DocModificationPrepend, metaClass, nullptr);
     if (!writeInjectDocumentation(s, TypeSystem::DocModificationReplace, metaClass, nullptr))
-        writeFormattedText(s, documentation.value(), metaClass);
+        writeFormattedText(s, documentation.value(Documentation::Detailed), metaClass);
 
     if (!metaClass->isNamespace())
         writeConstructors(s, metaClass);