Add support for briefdescription in doxygen parse

Extract briefdescription from doxygen files and make sure to
generate sphinx docs with it

Change-Id: Ibd2b104a2c85de6c3db1e8a48add061c804bd489
Reviewed-by: Friedemann Kleint <Friedemann.Kleint@qt.io>

5 files changed, 135 insertions, 66 deletions

diff --git a/sources/shiboken2/ApiExtractor/abstractmetalang.cpp b/sources/shiboken2/ApiExtractor/abstractmetalang.cpp
index 8e1f0d7e5..9d770284a 100644
--- a/sources/shiboken2/ApiExtractor/abstractmetalang.cpp
+++ b/sources/shiboken2/ApiExtractor/abstractmetalang.cpp
@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2019 The Qt Company Ltd.
+** Copyright (C) 2020 The Qt Company Ltd.
 ** Contact: https://www.qt.io/licensing/
 **
 ** This file is part of Qt for Python.
@@ -88,6 +88,49 @@ const AbstractMetaClass *recurseClassHierarchy(const AbstractMetaClass *klass,
 }
 
 /*******************************************************************************
+ * Documentation
+ */
+
+Documentation::Documentation(const QString &value, Documentation::Type t, Documentation::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;
+}
+
+QString Documentation::value(Documentation::Type t) const
+{
+    return m_data.value(t);
+}
+
+void Documentation::setValue(const QString &value, Documentation::Type t, Documentation::Format fmt)
+{
+    const QString v = value.trimmed();
+    if (v.isEmpty())
+        m_data.remove(t);
+    else
+        m_data[t] = value.trimmed();
+    m_format = fmt;
+}
+
+Documentation::Format Documentation::format() const
+{
+    return m_format;
+}
+
+void Documentation::setFormat(Documentation::Format f)
+{
+    m_format = f;
+}
+
+/*******************************************************************************
  * AbstractMetaVariable
  */
 
diff --git a/sources/shiboken2/ApiExtractor/abstractmetalang.h b/sources/shiboken2/ApiExtractor/abstractmetalang.h
index d99a54fc2..de7a1e3a5 100644
--- a/sources/shiboken2/ApiExtractor/abstractmetalang.h
+++ b/sources/shiboken2/ApiExtractor/abstractmetalang.h
@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2019 The Qt Company Ltd.
+** Copyright (C) 2020 The Qt Company Ltd.
 ** Contact: https://www.qt.io/licensing/
 **
 ** This file is part of Qt for Python.
@@ -39,6 +39,7 @@
 
 #include <QtCore/qobjectdefs.h>
 #include <QtCore/QStringList>
+#include <QtCore/QMap>
 
 QT_FORWARD_DECLARE_CLASS(QDebug)
 
@@ -72,34 +73,27 @@ public:
         Native,
         Target
     };
+    enum Type {
+        Detailed,
+        Brief,
+        Last
+    };
 
     Documentation() = default;
+    Documentation(const QString& value, Type t = Documentation::Detailed,
+                  Format fmt = Documentation::Native);
 
-    Documentation(const QString& value, Format fmt = Documentation::Native)
-            : m_data(value.trimmed()), m_format(fmt) {}
-
-    bool isEmpty() const { return m_data.isEmpty(); }
-
-    QString value() const
-    {
-        return m_data;
-    }
-
-    void setValue(const QString& value, Format fmt = Documentation::Native)
-    {
-        m_data = value.trimmed();
-        m_format = fmt;
-    }
+    bool isEmpty() const;
 
-    Documentation::Format format() const
-    {
-        return m_format;
-    }
+    QString value(Type t = Documentation::Detailed) const;
+    void setValue(const QString& value, Type t = Documentation::Detailed,
+                  Format fmt = Documentation::Native);
 
-    void setFormat(Format f) { m_format = f; }
+    Documentation::Format format() const;
+    void setFormat(Format f);
 
 private:
-    QString m_data;
+    QMap<Type, QString> m_data;
     Format m_format = Documentation::Native;
 
 };
diff --git a/sources/shiboken2/ApiExtractor/doxygenparser.cpp b/sources/shiboken2/ApiExtractor/doxygenparser.cpp
index 7c15db1ca..9fceb4328 100644
--- a/sources/shiboken2/ApiExtractor/doxygenparser.cpp
+++ b/sources/shiboken2/ApiExtractor/doxygenparser.cpp
@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2016 The Qt Company Ltd.
+** Copyright (C) 2020 The Qt Company Ltd.
 ** Contact: https://www.qt.io/licensing/
 **
 ** This file is part of Qt for Python.
@@ -94,12 +94,24 @@ void DoxygenParser::fillDocumentation(AbstractMetaClass* metaClass)
         return;
     }
 
+    static const QList<QPair<Documentation::Type, QString>> docTags = {
+        { Documentation::Brief,  QLatin1String("briefdescription") },
+        { Documentation::Detailed,  QLatin1String("detaileddescription") }
+    };
     // Get class documentation
-    const QString classQuery = QLatin1String("/doxygen/compounddef/detaileddescription");
-    QString classDoc = getDocumentation(xquery, classQuery,
-                                        metaClass->typeEntry()->docModifications());
-    if (classDoc.isEmpty())
-        qCWarning(lcShibokenDoc, "%s", qPrintable(msgCannotFindDocumentation(doxyFilePath, "class", metaClass->name(), classQuery)));
+    Documentation classDoc;
+
+    for (const auto &tag : docTags) {
+        const QString classQuery = QLatin1String("/doxygen/compounddef/") + tag.second;
+        QString doc = getDocumentation(xquery, classQuery,
+                                            metaClass->typeEntry()->docModifications());
+        if (doc.isEmpty())
+            qCWarning(lcShibokenDoc, "%s",
+                      qPrintable(msgCannotFindDocumentation(doxyFilePath, "class", metaClass->name(),
+                                                            classQuery)));
+        else
+            classDoc.setValue(doc, tag.first);
+    }
     metaClass->setDocumentation(classDoc);
 
     //Functions Documentation
@@ -128,28 +140,38 @@ void DoxygenParser::fillDocumentation(AbstractMetaClass* metaClass)
                     if (!arg->type()->isPrimitive()) {
                         query += QLatin1String("/../param[") + QString::number(i)
                                  + QLatin1String("]/type/ref[text()=\"")
-                                 + arg->type()->name() + QLatin1String("\"]/../..");
+                                 + arg->type()->cppSignature().toHtmlEscaped()
+                                 + QLatin1String("\"]/../..");
                     } else {
                         query += QLatin1String("/../param[") + QString::number(i)
-                                 + QLatin1String("]/type[text()=\"")
-                                 + arg->type()->name() + QLatin1String("\"]/..");
+                                 + QLatin1String("]/type[text(), \"")
+                                 + arg->type()->cppSignature().toHtmlEscaped()
+                                 + QLatin1String("\"]/..");
                     }
                     ++i;
                 }
             }
         }
-        if (!isProperty) {
-            query += QLatin1String("/../detaileddescription");
-        } else {
-            query = QLatin1Char('(') + query;
-            query += QLatin1String("/../detaileddescription)[1]");
-        }
-        QString doc = getDocumentation(xquery, query, DocModificationList());
-        if (doc.isEmpty()) {
-            qCWarning(lcShibokenDoc, "%s",
-                      qPrintable(msgCannotFindDocumentation(doxyFilePath, metaClass, func, query)));
+        Documentation funcDoc;
+        for (const auto &tag : docTags) {
+            QString funcQuery(query);
+            if (!isProperty) {
+                funcQuery += QLatin1String("/../") + tag.second;
+            } else {
+                funcQuery = QLatin1Char('(') + funcQuery;
+                funcQuery += QLatin1String("/../%1)[1]").arg(tag.second);
+            }
+
+            QString doc = getDocumentation(xquery, funcQuery, DocModificationList());
+            if (doc.isEmpty()) {
+                qCWarning(lcShibokenDoc, "%s",
+                          qPrintable(msgCannotFindDocumentation(doxyFilePath, metaClass, func,
+                                                                funcQuery)));
+            } else {
+                funcDoc.setValue(doc, tag.first);
+            }
         }
-        func->setDocumentation(doc);
+        func->setDocumentation(funcDoc);
         isProperty = false;
     }
 
@@ -159,14 +181,20 @@ void DoxygenParser::fillDocumentation(AbstractMetaClass* metaClass)
         if (field->isPrivate())
             return;
 
-        QString query = QLatin1String("/doxygen/compounddef/sectiondef/memberdef/name[text()=\"")
-                        + field->name() + QLatin1String("\"]/../detaileddescription");
-        QString doc = getDocumentation(xquery, query, DocModificationList());
-        if (doc.isEmpty()) {
-            qCWarning(lcShibokenDoc, "%s",
-                      qPrintable(msgCannotFindDocumentation(doxyFilePath, metaClass, field, query)));
+        Documentation fieldDoc;
+        for (const auto &tag : docTags) {
+            QString query = QLatin1String("/doxygen/compounddef/sectiondef/memberdef/name[text()=\"")
+                            + field->name() + QLatin1String("\"]/../") + tag.second;
+            QString doc = getDocumentation(xquery, query, DocModificationList());
+            if (doc.isEmpty()) {
+                qCWarning(lcShibokenDoc, "%s",
+                          qPrintable(msgCannotFindDocumentation(doxyFilePath, metaClass, field,
+                                                                query)));
+            } else {
+                fieldDoc.setValue(doc, tag.first);
+            }
         }
-        field->setDocumentation(doc);
+        field->setDocumentation(fieldDoc);
     }
 
     //Enums
diff --git a/sources/shiboken2/generator/qtdoc/qtdocgenerator.cpp b/sources/shiboken2/generator/qtdoc/qtdocgenerator.cpp
index a9413607d..f7dfc5391 100644
--- a/sources/shiboken2/generator/qtdoc/qtdocgenerator.cpp
+++ b/sources/shiboken2/generator/qtdoc/qtdocgenerator.cpp
@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2016 The Qt Company Ltd.
+** Copyright (C) 2020 The Qt Company Ltd.
 ** Contact: https://www.qt.io/licensing/
 **
 ** This file is part of Qt for Python.
@@ -1535,7 +1535,8 @@ QString QtDocGenerator::fileNameForContext(const GeneratorContext &context) cons
 }
 
 void QtDocGenerator::writeFormattedText(QTextStream &s, const Documentation &doc,
-                                        const AbstractMetaClass *metaClass)
+                                        const AbstractMetaClass *metaClass,
+                                        Documentation::Type docType)
 {
     QString metaClassName;
 
@@ -1543,10 +1544,10 @@ void QtDocGenerator::writeFormattedText(QTextStream &s, const Documentation &doc
         metaClassName = metaClass->fullName();
 
     if (doc.format() == Documentation::Native) {
-        QtXmlToSphinx x(this, doc.value(), metaClassName);
+        QtXmlToSphinx x(this,doc.value(docType), metaClassName);
         s << x;
     } else {
-        const QString &value = doc.value();
+        const QString &value = doc.value(docType);
         const QVector<QStringRef> lines = value.splitRef(QLatin1Char('\n'));
         int typesystemIndentation = std::numeric_limits<int>::max();
         // check how many spaces must be removed from the beginning of each line
@@ -1631,7 +1632,7 @@ void QtDocGenerator::generateClass(QTextStream &s, const GeneratorContext &class
     auto documentation = metaClass->documentation();
     Documentation brief;
     if (extractBrief(&documentation, &brief))
-        writeFormattedText(s, brief, metaClass);
+        writeFormattedText(s, brief.value(), metaClass);
 
     s << ".. inheritance-diagram:: " << metaClass->fullName() << Qt::endl
       << "    :parts: 2" << Qt::endl << Qt::endl;
@@ -1658,7 +1659,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, metaClass);
+        writeFormattedText(s, documentation.value(), metaClass);
 
     if (!metaClass->isNamespace())
         writeConstructors(s, metaClass);
@@ -1764,7 +1765,7 @@ void QtDocGenerator::writeEnums(QTextStream& s, const AbstractMetaClass* cppClas
     const AbstractMetaEnumList &enums = cppClass->enums();
     for (AbstractMetaEnum *en : enums) {
         s << section_title << cppClass->fullName() << '.' << en->name() << Qt::endl << Qt::endl;
-        writeFormattedText(s, en->documentation(), cppClass);
+        writeFormattedText(s, en->documentation().value(), cppClass);
         const auto version = versionOf(en->typeEntry());
         if (!version.isNull())
             s << rstVersionAdded(version);
@@ -1780,7 +1781,7 @@ void QtDocGenerator::writeFields(QTextStream& s, const AbstractMetaClass* cppCla
     for (AbstractMetaField *field : fields) {
         s << section_title << cppClass->fullName() << "." << field->name() << Qt::endl << Qt::endl;
         //TODO: request for member ‘documentation’ is ambiguous
-        writeFormattedText(s, field->AbstractMetaAttributes::documentation(), cppClass);
+        writeFormattedText(s, field->AbstractMetaAttributes::documentation().value(), cppClass);
     }
 }
 
@@ -1836,7 +1837,7 @@ void QtDocGenerator::writeConstructors(QTextStream& s, const AbstractMetaClass*
     s << Qt::endl;
 
     for (AbstractMetaFunction *func : qAsConst(lst))
-        writeFormattedText(s, func->documentation(), cppClass);
+        writeFormattedText(s, func->documentation().value(), cppClass);
 }
 
 QString QtDocGenerator::parseArgDocStyle(const AbstractMetaClass* /* cppClass */,
@@ -1971,8 +1972,8 @@ bool QtDocGenerator::writeInjectDocumentation(QTextStream& s,
                 else
                     continue;
 
-                doc.setValue(mod.code() , fmt);
-                writeFormattedText(s, doc, cppClass);
+                doc.setValue(mod.code(), Documentation::Detailed, fmt);
+                writeFormattedText(s, doc.value(), cppClass);
                 didSomething = true;
             }
         }
@@ -2122,10 +2123,11 @@ void QtDocGenerator::writeFunction(QTextStream& s, const AbstractMetaClass* cppC
         if (func->attributes().testFlag(AbstractMetaAttributes::Deprecated))
             s << INDENT << rstDeprecationNote("function");
     }
-
     writeInjectDocumentation(s, TypeSystem::DocModificationPrepend, cppClass, func);
-    if (!writeInjectDocumentation(s, TypeSystem::DocModificationReplace, cppClass, func))
-        writeFormattedText(s, func->documentation(), cppClass);
+    if (!writeInjectDocumentation(s, TypeSystem::DocModificationReplace, cppClass, func)) {
+        writeFormattedText(s, func->documentation(), cppClass, Documentation::Brief);
+        writeFormattedText(s, func->documentation(), cppClass, Documentation::Detailed);
+    }
     writeInjectDocumentation(s, TypeSystem::DocModificationAppend, cppClass, func);
 }
 
diff --git a/sources/shiboken2/generator/qtdoc/qtdocgenerator.h b/sources/shiboken2/generator/qtdoc/qtdocgenerator.h
index 468abd599..b0f4c2552 100644
--- a/sources/shiboken2/generator/qtdoc/qtdocgenerator.h
+++ b/sources/shiboken2/generator/qtdoc/qtdocgenerator.h
@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2016 The Qt Company Ltd.
+** Copyright (C) 2020 The Qt Company Ltd.
 ** Contact: https://www.qt.io/licensing/
 **
 ** This file is part of Qt for Python.
@@ -33,6 +33,7 @@
 #include <QtCore/QScopedPointer>
 #include <QtCore/QTextStream>
 #include <QXmlStreamReader>
+#include "abstractmetalang.h"
 #include "generator.h"
 #include "docparser.h"
 #include "typesystem_enums.h"
@@ -261,7 +262,8 @@ private:
 
     void writeConstructors(QTextStream &s, const AbstractMetaClass *cppClass);
     void writeFormattedText(QTextStream &s, const Documentation &doc,
-                            const AbstractMetaClass *metaclass = nullptr);
+                            const AbstractMetaClass *metaclass = nullptr,
+                            Documentation::Type docType = Documentation::Detailed);
     bool writeInjectDocumentation(QTextStream& s, TypeSystem::DocModificationMode mode, const AbstractMetaClass* cppClass, const AbstractMetaFunction* func);
     void writeDocSnips(QTextStream &s, const CodeSnipList &codeSnips, TypeSystem::CodeSnipPosition position, TypeSystem::Language language);