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.

Pick-to: 5.15
Change-Id: I86b37ae1c4a92f96508a03f5dbcfb6dc56014382
Reviewed-by: Cristian Maureira-Fredes <cristian.maureira-fredes@qt.io>
Reviewed-by: Christian Tismer <tismer@stackless.com>

4 files changed, 41 insertions, 37 deletions

diff --git a/sources/shiboken6/ApiExtractor/documentation.h b/sources/shiboken6/ApiExtractor/documentation.h
index b0083c2be..70bfe3292 100644
--- a/sources/shiboken6/ApiExtractor/documentation.h
+++ b/sources/shiboken6/ApiExtractor/documentation.h
@@ -50,6 +50,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/shiboken6/ApiExtractor/qtdocparser.cpp b/sources/shiboken6/ApiExtractor/qtdocparser.cpp
index 3b5837c95..abd781cb4 100644
--- a/sources/shiboken6/ApiExtractor/qtdocparser.cpp
+++ b/sources/shiboken6/ApiExtractor/qtdocparser.cpp
@@ -46,6 +46,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());
@@ -215,6 +218,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)
@@ -266,9 +288,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/shiboken6/ApiExtractor/tests/testmodifydocumentation.cpp b/sources/shiboken6/ApiExtractor/tests/testmodifydocumentation.cpp
index a88c8554a..4bf1b8455 100644
--- a/sources/shiboken6/ApiExtractor/tests/testmodifydocumentation.cpp
+++ b/sources/shiboken6/ApiExtractor/tests/testmodifydocumentation.cpp
@@ -74,13 +74,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>
@@ -88,7 +89,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/shiboken6/generator/qtdoc/qtdocgenerator.cpp b/sources/shiboken6/generator/qtdoc/qtdocgenerator.cpp
index 7e0664121..215e756de 100644
--- a/sources/shiboken6/generator/qtdoc/qtdocgenerator.cpp
+++ b/sources/shiboken6/generator/qtdoc/qtdocgenerator.cpp
@@ -56,9 +56,6 @@
 
 static inline QString additionalDocumentationOption() { return QStringLiteral("additional-documentation"); }
 
-static inline QString briefStartElement() { return QStringLiteral("<brief>"); }
-static inline QString briefEndElement() { return QStringLiteral("</brief>"); }
-
 static inline QString none() { return QStringLiteral("None"); }
 
 static bool shouldSkip(const AbstractMetaFunctionCPtr &func)
@@ -235,30 +232,6 @@ static void writeInheritedByList(TextStream& s, const AbstractMetaClass* metaCla
     s << classes.join(QLatin1String(", ")) << "\n\n";
 }
 
-// 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(TextStream &s, const GeneratorContext &classContext)
 {
     const AbstractMetaClass *metaClass = classContext.metaClass();
@@ -277,9 +250,8 @@ void QtDocGenerator::generateClass(TextStream &s, const GeneratorContext &classC
     s << Pad('*', className.count()) << "\n\n";
 
     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()<< '\n'
       << "    :parts: 2\n\n";
@@ -306,7 +278,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(), metaClass);
+        writeFormattedText(s, documentation.value(Documentation::Detailed), metaClass);
 
     if (!metaClass->isNamespace())
         writeConstructors(s, metaClass);