diff options
author | Renato Araujo Oliveira Filho <renato.araujo@kdab.com> | 2020-04-16 10:24:07 -0300 |
---|---|---|
committer | Renato Araujo Oliveira Filho <renato.araujo@kdab.com> | 2020-09-02 10:48:12 -0300 |
commit | b3b9a9714c0f1199d547854be6d2d47a9268d444 (patch) | |
tree | 0ebfb4d3e069f4caa9f717c641414119d2f4b6c0 /sources/shiboken2/ApiExtractor | |
parent | 61d1a5af4e6f17da32e302023b8a4358bccf5863 (diff) |
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>
Diffstat (limited to 'sources/shiboken2/ApiExtractor')
-rw-r--r-- | sources/shiboken2/ApiExtractor/abstractmetalang.cpp | 45 | ||||
-rw-r--r-- | sources/shiboken2/ApiExtractor/abstractmetalang.h | 38 | ||||
-rw-r--r-- | sources/shiboken2/ApiExtractor/doxygenparser.cpp | 82 |
3 files changed, 115 insertions, 50 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 |