aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorFriedemann Kleint <Friedemann.Kleint@qt.io>2023-12-08 15:00:45 +0100
committerFriedemann Kleint <Friedemann.Kleint@qt.io>2023-12-12 10:26:49 +0100
commit9cde3eafa776f1c942db6535fbf4303b35ccc73e (patch)
tree5c1c858b7fa62d265d3b5ace7c95ed38169af41c
parentd8003770fc55c5bf6c0857797f5a416d01d73d94 (diff)
DocGenerator: Further preparations for generating global functions/enums
QtDocGenerator::writeInjectDocumentation() previously had class and function as parameters and was used for class documentation (function == 0) as well as function documentation. Split it into separate functions for both cases such that class can be 0 in the function case for global functions. Remove the indentation, which appeared to be misguided. Add separate functions for querying the XPATH modifications. Task-number: PYSIDE-1106 Task-number: PYSIDE-2543 Change-Id: I78a25f100b810abb542d82be56c4473816bb8c82 Reviewed-by: Cristian Maureira-Fredes <cristian.maureira-fredes@qt.io>
Diffstat
-rw-r--r--sources/shiboken6/ApiExtractor/docparser.cpp113
-rw-r--r--sources/shiboken6/ApiExtractor/docparser.h10
-rw-r--r--sources/shiboken6/ApiExtractor/doxygenparser.cpp2
-rw-r--r--sources/shiboken6/ApiExtractor/qtdocparser.cpp4
-rw-r--r--sources/shiboken6/generator/qtdoc/qtdocgenerator.cpp58
-rw-r--r--sources/shiboken6/generator/qtdoc/qtdocgenerator.h10
6 files changed, 138 insertions, 59 deletions
diff --git a/sources/shiboken6/ApiExtractor/docparser.cpp b/sources/shiboken6/ApiExtractor/docparser.cpp
index dbb09842a..2ea764a21 100644
--- a/sources/shiboken6/ApiExtractor/docparser.cpp
+++ b/sources/shiboken6/ApiExtractor/docparser.cpp
@@ -31,6 +31,26 @@
using namespace Qt::StringLiterals;
+static inline bool isXpathDocModification(const DocModification &mod)
+{
+ return mod.mode() == TypeSystem::DocModificationXPathReplace;
+}
+
+static inline bool isNotXpathDocModification(const DocModification &mod)
+{
+ return mod.mode() != TypeSystem::DocModificationXPathReplace;
+}
+
+static void removeXpathDocModifications(DocModificationList *l)
+{
+ l->erase(std::remove_if(l->begin(), l->end(), isXpathDocModification), l->end());
+}
+
+static void removeNonXpathDocModifications(DocModificationList *l)
+{
+ l->erase(std::remove_if(l->begin(), l->end(), isNotXpathDocModification), l->end());
+}
+
DocParser::DocParser()
{
#ifdef HAVE_LIBXSLT
@@ -86,22 +106,59 @@ bool DocParser::skipForQuery(const AbstractMetaFunctionCPtr &func)
usesRValueReference);
}
-DocModificationList DocParser::getDocModifications(const AbstractMetaClassCPtr &cppClass,
- const AbstractMetaFunctionCPtr &func)
+DocModificationList DocParser::getDocModifications(const AbstractMetaClassCPtr &cppClass)
+
{
- auto te = cppClass->typeEntry();
- if (!func)
- return te->docModifications();
+ auto result = cppClass->typeEntry()->docModifications();
+ removeXpathDocModifications(&result);
+ return result;
+}
- if (func->isUserAdded())
- return func->addedFunctionDocModifications();
+static void filterBySignature(const AbstractMetaFunctionCPtr &func, DocModificationList *l)
+{
+ if (!l->isEmpty()) {
+ const QString minimalSignature = func->minimalSignature();
+ const auto filter = [&minimalSignature](const DocModification &mod) {
+ return mod.signature() != minimalSignature;
+ };
+ l->erase(std::remove_if(l->begin(), l->end(), filter), l->end());
+ }
+}
+
+DocModificationList DocParser::getDocModifications(const AbstractMetaFunctionCPtr &func,
+ const AbstractMetaClassCPtr &cppClass)
+{
+ DocModificationList result;
+ if (func->isUserAdded()) {
+ result = func->addedFunctionDocModifications();
+ removeXpathDocModifications(&result);
+ } else if (cppClass != nullptr) {
+ result = cppClass->typeEntry()->functionDocModifications();
+ removeXpathDocModifications(&result);
+ filterBySignature(func, &result);
+ }
+ return result;
+}
+
+DocModificationList DocParser::getXpathDocModifications(const AbstractMetaClassCPtr &cppClass)
+{
+ auto result = cppClass->typeEntry()->docModifications();
+ removeNonXpathDocModifications(&result);
+ return result;
+}
- DocModificationList result = te->functionDocModifications();
- const QString minimalSignature = func->minimalSignature();
- const auto filter = [&minimalSignature](const DocModification &mod) {
- return mod.signature() != minimalSignature;
- };
- result.erase(std::remove_if(result.begin(), result.end(), filter), result.end());
+DocModificationList DocParser::getXpathDocModifications(const AbstractMetaFunctionCPtr &func,
+ const AbstractMetaClassCPtr &cppClass)
+{
+ DocModificationList result;
+ if (func->isUserAdded()) {
+ result = func->addedFunctionDocModifications();
+ removeNonXpathDocModifications(&result);
+ } else if (cppClass != nullptr) {
+ result = cppClass->typeEntry()->functionDocModifications();
+ removeNonXpathDocModifications(&result);
+ filterBySignature(func, &result);
+ }
return result;
}
@@ -131,12 +188,8 @@ AbstractMetaFunctionCList DocParser::documentableFunctions(const AbstractMetaCla
return result;
}
-static inline bool isXpathDocModification(const DocModification &mod)
-{
- return mod.mode() == TypeSystem::DocModificationXPathReplace;
-}
-
-QString DocParser::applyDocModifications(const DocModificationList& mods, const QString& xml)
+QString DocParser::applyDocModifications(const DocModificationList& xpathMods,
+ const QString& xml)
{
const char xslPrefix[] =
R"(<xsl:template match="/">
@@ -150,32 +203,28 @@ R"(<xsl:template match="/">
</xsl:template>
)";
- if (mods.isEmpty() || xml.isEmpty()
- || !std::any_of(mods.cbegin(), mods.cend(), isXpathDocModification)) {
+ if (xpathMods.isEmpty() || xml.isEmpty())
return xml;
- }
QString xsl = QLatin1StringView(xslPrefix);
- for (const DocModification &mod : mods) {
- if (isXpathDocModification(mod)) {
- QString xpath = mod.xpath();
- xpath.replace(u'"', u"&quot;"_s);
- xsl += u"<xsl:template match=\""_s
- + xpath + u"\">"_s
- + mod.code() + u"</xsl:template>\n"_s;
- }
+ for (const DocModification &mod : xpathMods) {
+ Q_ASSERT(isXpathDocModification(mod));
+ QString xpath = mod.xpath();
+ xpath.replace(u'"', u"&quot;"_s);
+ xsl += "<xsl:template match=\""_L1 + xpath + "\">"_L1
+ + mod.code() + "</xsl:template>\n"_L1;
}
QString errorMessage;
const QString result = xsl_transform(xml, xsl, &errorMessage);
if (!errorMessage.isEmpty())
qCWarning(lcShibokenDoc, "%s",
- qPrintable(msgXpathDocModificationError(mods, errorMessage)));
+ qPrintable(msgXpathDocModificationError(xpathMods, errorMessage)));
if (result == xml) {
const QString message = u"Query did not result in any modifications to \""_s
+ xml + u'"';
qCWarning(lcShibokenDoc, "%s",
- qPrintable(msgXpathDocModificationError(mods, message)));
+ qPrintable(msgXpathDocModificationError(xpathMods, message)));
}
return result;
}
diff --git a/sources/shiboken6/ApiExtractor/docparser.h b/sources/shiboken6/ApiExtractor/docparser.h
index b5640d1d9..1e15ca661 100644
--- a/sources/shiboken6/ApiExtractor/docparser.h
+++ b/sources/shiboken6/ApiExtractor/docparser.h
@@ -94,8 +94,12 @@ public:
/// Helper to return the documentation modifications for a class
/// or a member function.
- static DocModificationList getDocModifications(const AbstractMetaClassCPtr &cppClass,
- const AbstractMetaFunctionCPtr &func = {});
+ static DocModificationList getDocModifications(const AbstractMetaClassCPtr &cppClass);
+ static DocModificationList getDocModifications(const AbstractMetaFunctionCPtr &func,
+ const AbstractMetaClassCPtr &cppClass = {});
+ static DocModificationList getXpathDocModifications(const AbstractMetaClassCPtr &cppClass);
+ static DocModificationList getXpathDocModifications(const AbstractMetaFunctionCPtr &func,
+ const AbstractMetaClassCPtr &cppClass = {});
static QString enumBaseClass(const AbstractMetaEnum &e);
@@ -106,7 +110,7 @@ protected:
static AbstractMetaFunctionCList documentableFunctions(const AbstractMetaClassCPtr &metaClass);
- static QString applyDocModifications(const DocModificationList &mods, const QString &xml);
+ static QString applyDocModifications(const DocModificationList &xpathMods, const QString &xml);
private:
QString m_packageName;
diff --git a/sources/shiboken6/ApiExtractor/doxygenparser.cpp b/sources/shiboken6/ApiExtractor/doxygenparser.cpp
index 2fdc3d1f6..feabcefed 100644
--- a/sources/shiboken6/ApiExtractor/doxygenparser.cpp
+++ b/sources/shiboken6/ApiExtractor/doxygenparser.cpp
@@ -151,7 +151,7 @@ void DoxygenParser::fillDocumentation(const AbstractMetaClassPtr &metaClass)
}
QString doc = getDocumentation(xquery, funcQuery,
- DocParser::getDocModifications(metaClass, func));
+ DocParser::getXpathDocModifications(func, metaClass));
if (doc.isEmpty()) {
qCWarning(lcShibokenDoc, "%s",
qPrintable(msgCannotFindDocumentation(doxyFilePath, func.get(),
diff --git a/sources/shiboken6/ApiExtractor/qtdocparser.cpp b/sources/shiboken6/ApiExtractor/qtdocparser.cpp
index af1fa6174..5aa6ebdca 100644
--- a/sources/shiboken6/ApiExtractor/qtdocparser.cpp
+++ b/sources/shiboken6/ApiExtractor/qtdocparser.cpp
@@ -112,7 +112,7 @@ QString QtDocParser::functionDocumentation(const QString &sourceFileName,
queryFunctionDocumentation(sourceFileName, classDocumentation, metaClass,
func, errorMessage);
- const auto funcModifs = DocParser::getDocModifications(metaClass, func);
+ const auto funcModifs = DocParser::getXpathDocModifications(func, metaClass);
return docString.isEmpty() || funcModifs.isEmpty()
? docString : applyDocModifications(funcModifs, docString);
}
@@ -242,7 +242,7 @@ void QtDocParser::fillDocumentation(const AbstractMetaClassPtr &metaClass)
metaClass->setPropertyDocumentation(p.name, doc);
}
- QString docString = applyDocModifications(metaClass->typeEntry()->docModifications(),
+ QString docString = applyDocModifications(DocParser::getXpathDocModifications(metaClass),
classDocumentation.description);
if (docString.isEmpty()) {
diff --git a/sources/shiboken6/generator/qtdoc/qtdocgenerator.cpp b/sources/shiboken6/generator/qtdoc/qtdocgenerator.cpp
index 59119b10e..49084eb86 100644
--- a/sources/shiboken6/generator/qtdoc/qtdocgenerator.cpp
+++ b/sources/shiboken6/generator/qtdoc/qtdocgenerator.cpp
@@ -403,8 +403,8 @@ void QtDocGenerator::generateClass(TextStream &s, const GeneratorContext &classC
s << '\n' << headline("Detailed Description") << ".. _More:\n";
- writeInjectDocumentation(s, TypeSystem::DocModificationPrepend, metaClass, nullptr);
- if (!writeInjectDocumentation(s, TypeSystem::DocModificationReplace, metaClass, nullptr))
+ writeInjectDocumentation(s, TypeSystem::DocModificationPrepend, metaClass);
+ if (!writeInjectDocumentation(s, TypeSystem::DocModificationReplace, metaClass))
writeFormattedDetailedText(s, documentation, scope);
if (!metaClass->isNamespace())
@@ -425,7 +425,7 @@ void QtDocGenerator::generateClass(TextStream &s, const GeneratorContext &classC
writeFunction(s, func, metaClass, scope, indexed);
}
- writeInjectDocumentation(s, TypeSystem::DocModificationAppend, metaClass, nullptr);
+ writeInjectDocumentation(s, TypeSystem::DocModificationAppend, metaClass);
}
void QtDocGenerator::writeFunctionToc(TextStream &s, const QString &title,
@@ -669,17 +669,12 @@ void QtDocGenerator::writeDocSnips(TextStream &s,
}
}
-bool QtDocGenerator::writeInjectDocumentation(TextStream &s,
- TypeSystem::DocModificationMode mode,
- const AbstractMetaClassCPtr &cppClass,
- const AbstractMetaFunctionCPtr &func)
+bool QtDocGenerator::writeDocModifications(TextStream &s,
+ const DocModificationList &mods,
+ TypeSystem::DocModificationMode mode,
+ const QString &scope) const
{
- Indentation indentation(s);
bool didSomething = false;
-
- const DocModificationList mods = DocParser::getDocModifications(cppClass, func);
- const QString scope = classScope(cppClass);
-
for (const DocModification &mod : mods) {
if (mod.mode() == mode) {
switch (mod.format()) {
@@ -696,17 +691,42 @@ bool QtDocGenerator::writeInjectDocumentation(TextStream &s,
}
}
}
+ return didSomething;
+}
+
+bool QtDocGenerator::writeInjectDocumentation(TextStream &s,
+ TypeSystem::DocModificationMode mode,
+ const AbstractMetaClassCPtr &cppClass)
+{
+ const bool didSomething =
+ writeDocModifications(s, DocParser::getDocModifications(cppClass),
+ mode, classScope(cppClass));
+ s << '\n';
+ // FIXME PYSIDE-7: Deprecate the use of doc string on glue code.
+ // This is pre "add-function" and "inject-documentation" tags.
+ const TypeSystem::CodeSnipPosition pos = mode == TypeSystem::DocModificationPrepend
+ ? TypeSystem::CodeSnipPositionBeginning : TypeSystem::CodeSnipPositionEnd;
+ writeDocSnips(s, cppClass->typeEntry()->codeSnips(), pos, TypeSystem::TargetLangCode);
+ return didSomething;
+}
+
+bool QtDocGenerator::writeInjectDocumentation(TextStream &s,
+ TypeSystem::DocModificationMode mode,
+ const AbstractMetaFunctionCPtr &func,
+ const AbstractMetaClassCPtr &cppClass,
+ const QString &scope)
+{
+ const bool didSomething =
+ writeDocModifications(s, DocParser::getDocModifications(func, cppClass),
+ mode, scope);
s << '\n';
// FIXME PYSIDE-7: Deprecate the use of doc string on glue code.
// This is pre "add-function" and "inject-documentation" tags.
const TypeSystem::CodeSnipPosition pos = mode == TypeSystem::DocModificationPrepend
? TypeSystem::CodeSnipPositionBeginning : TypeSystem::CodeSnipPositionEnd;
- if (func)
- writeDocSnips(s, func->injectedCodeSnips(), pos, TypeSystem::TargetLangCode);
- else
- writeDocSnips(s, cppClass->typeEntry()->codeSnips(), pos, TypeSystem::TargetLangCode);
+ writeDocSnips(s, func->injectedCodeSnips(), pos, TypeSystem::TargetLangCode);
return didSomething;
}
@@ -861,12 +881,12 @@ void QtDocGenerator::writeFunction(TextStream &s, const AbstractMetaFunctionCPtr
if (func->isDeprecated())
s << rstDeprecationNote("function");
}
- writeInjectDocumentation(s, TypeSystem::DocModificationPrepend, cppClass, func);
- if (!writeInjectDocumentation(s, TypeSystem::DocModificationReplace, cppClass, func)) {
+ writeInjectDocumentation(s, TypeSystem::DocModificationPrepend, func, cppClass, scope);
+ if (!writeInjectDocumentation(s, TypeSystem::DocModificationReplace, func, cppClass, scope)) {
writeFormattedBriefText(s, func->documentation(), scope);
writeFormattedDetailedText(s, func->documentation(), scope);
}
- writeInjectDocumentation(s, TypeSystem::DocModificationAppend, cppClass, func);
+ writeInjectDocumentation(s, TypeSystem::DocModificationAppend, func, cppClass, scope);
if (auto propIndex = func->propertySpecIndex(); propIndex >= 0) {
const QString name = cppClass->propertySpecs().at(propIndex).name();
diff --git a/sources/shiboken6/generator/qtdoc/qtdocgenerator.h b/sources/shiboken6/generator/qtdoc/qtdocgenerator.h
index 0bdfa4f0a..79c2872c2 100644
--- a/sources/shiboken6/generator/qtdoc/qtdocgenerator.h
+++ b/sources/shiboken6/generator/qtdoc/qtdocgenerator.h
@@ -95,8 +95,14 @@ private:
const QString &scope = {}) const;
bool writeInjectDocumentation(TextStream &s, TypeSystem::DocModificationMode mode,
- const AbstractMetaClassCPtr &cppClass,
- const AbstractMetaFunctionCPtr &func);
+ const AbstractMetaClassCPtr &cppClass);
+ bool writeInjectDocumentation(TextStream &s, TypeSystem::DocModificationMode mode,
+ const AbstractMetaFunctionCPtr &func,
+ const AbstractMetaClassCPtr &cppClass = {},
+ const QString &scope = {});
+ bool writeDocModifications(TextStream &s, const DocModificationList &mods,
+ TypeSystem::DocModificationMode mode,
+ const QString &scope = {}) const;
static void writeDocSnips(TextStream &s, const CodeSnipList &codeSnips,
TypeSystem::CodeSnipPosition position, TypeSystem::Language language);
generated by cgit v1.2.3 (git 2.25.1) at 2025-12-18 05:29:10 +0000