From 1c4b7ddb0f879909f5d2f9f6207c06dfd2493340 Mon Sep 17 00:00:00 2001 From: Friedemann Kleint Date: Tue, 13 Apr 2021 13:31:58 +0200 Subject: 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 Reviewed-by: Christian Tismer --- sources/shiboken6/ApiExtractor/documentation.h | 1 + sources/shiboken6/ApiExtractor/qtdocparser.cpp | 36 ++++++++++++++++++++-- .../ApiExtractor/tests/testmodifydocumentation.cpp | 7 +++-- .../shiboken6/generator/qtdoc/qtdocgenerator.cpp | 34 ++------------------ 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 #include +static inline QString briefStartElement() { return QStringLiteral(""); } +static inline QString briefEndElement() { return QStringLiteral(""); } + Documentation QtDocParser::retrieveModuleDocumentation() { return retrieveModuleDocumentation(packageName()); @@ -215,6 +218,25 @@ QString QtDocParser::queryFunctionDocumentation(const QString &sourceFileName, return result; } +// Extract the 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(" More_...")); + 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"( 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"( oi -Modified Brief Paragraph number 1 Paragraph number 2 Some changed contents here @@ -88,7 +89,7 @@ R"( )"; 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(""); } -static inline QString briefEndElement() { return QStringLiteral(""); } - 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 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(" More_...")); - 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); -- cgit v1.2.3