From 166a9ca4c0a07af94ea72d767ca0e9dd28552786 Mon Sep 17 00:00:00 2001 From: Friedemann Kleint Date: Tue, 12 Mar 2019 15:15:24 +0100 Subject: shiboken: Fix the formatting of function signatures Replace the note directive previously used for \since by the standard versionadd directive which takes less space. Move it below the function parameters and indent it along with the parameters correctly as otherwise the formatting is messed up. Change writeFunctionSignature() to return a QString which is more convenient for indenting. Remove the bool writeDoc parameter from QtDocGenerator::writeFunction() and spell out the formatting in writeConstructors() since it all needs to be indented properly (using the new indenter helper). Change-Id: I2294ba457ed05f431be295f9d42489aeb6805a8a Reviewed-by: Cristian Maureira-Fredes --- .../shiboken2/generator/qtdoc/qtdocgenerator.cpp | 81 ++++++++++++++-------- sources/shiboken2/generator/qtdoc/qtdocgenerator.h | 5 +- 2 files changed, 56 insertions(+), 30 deletions(-) (limited to 'sources/shiboken2') diff --git a/sources/shiboken2/generator/qtdoc/qtdocgenerator.cpp b/sources/shiboken2/generator/qtdoc/qtdocgenerator.cpp index c194c0ea4..c22abd6ab 100644 --- a/sources/shiboken2/generator/qtdoc/qtdocgenerator.cpp +++ b/sources/shiboken2/generator/qtdoc/qtdocgenerator.cpp @@ -167,12 +167,27 @@ static QTextStream &ensureEndl(QTextStream &s) return s; } -static void formatSince(QTextStream &s, const char *what, const TypeEntry *te) +static inline QVersionNumber versionOf(const TypeEntry *te) { - if (te && te->version() > QVersionNumber(0, 0)) { - s << ".. note:: This " << what << " was introduced in Qt " - << te->version().toString() << '.' << endl; + if (te) { + const auto version = te->version(); + if (!version.isNull() && version > QVersionNumber(0, 0)) + return version; } + return QVersionNumber(); +} + +struct rstVersionAdded +{ + explicit rstVersionAdded(const QVersionNumber &v) : m_version(v) {} + + const QVersionNumber m_version; +}; + +static QTextStream &operator<<(QTextStream &s, const rstVersionAdded &v) +{ + s << ".. versionadded:: "<< v.m_version.toString() << "\n\n"; + return s; } // RST anchor string: Anything else but letters, numbers, '_' or '.' replaced by '-' @@ -1576,7 +1591,9 @@ void QtDocGenerator::generateClass(QTextStream &s, GeneratorContext &classContex writeInheritedByList(s, metaClass, classes()); - formatSince(s, "class", metaClass->typeEntry()); + const auto version = versionOf(metaClass->typeEntry()); + if (!version.isNull()) + s << rstVersionAdded(version); writeFunctionList(s, metaClass); @@ -1608,7 +1625,7 @@ void QtDocGenerator::generateClass(QTextStream &s, GeneratorContext &classContex else s << ".. method:: "; - writeFunction(s, true, metaClass, func); + writeFunction(s, metaClass, func); } writeInjectDocumentation(s, TypeSystem::DocModificationAppend, metaClass, 0); @@ -1697,7 +1714,9 @@ void QtDocGenerator::writeEnums(QTextStream& s, const AbstractMetaClass* cppClas for (AbstractMetaEnum *en : enums) { s << section_title << getClassTargetFullName(cppClass) << '.' << en->name() << endl << endl; writeFormattedText(s, en->documentation(), cppClass); - formatSince(s, "enum", en->typeEntry()); + const auto version = versionOf(en->typeEntry()); + if (!version.isNull()) + s << rstVersionAdded(version); } } @@ -1717,7 +1736,6 @@ void QtDocGenerator::writeFields(QTextStream& s, const AbstractMetaClass* cppCla void QtDocGenerator::writeConstructors(QTextStream& s, const AbstractMetaClass* cppClass) { static const QString sectionTitle = QLatin1String(".. class:: "); - static const QString sectionTitleSpace = QString(sectionTitle.size(), QLatin1Char(' ')); AbstractMetaFunctionList lst = cppClass->queryFunctions(AbstractMetaClass::Constructors | AbstractMetaClass::Visible); for (int i = lst.size() - 1; i >= 0; --i) { @@ -1728,14 +1746,21 @@ void QtDocGenerator::writeConstructors(QTextStream& s, const AbstractMetaClass* bool first = true; QHash arg_map; + IndentorBase<1> indent1; + indent1.indent = INDENT.total(); for (AbstractMetaFunction *func : qAsConst(lst)) { + s << indent1; if (first) { first = false; s << sectionTitle; - } else { - s << sectionTitleSpace; + indent1.indent += sectionTitle.size(); } - writeFunction(s, false, cppClass, func); + s << functionSignature(cppClass, func) << "\n\n"; + + const auto version = versionOf(func->typeEntry()); + if (!version.isNull()) + s << indent1 << rstVersionAdded(version); + const AbstractMetaArgumentList &arguments = func->arguments(); for (AbstractMetaArgument *arg : arguments) { if (!arg_map.contains(arg->name())) { @@ -1747,7 +1772,7 @@ void QtDocGenerator::writeConstructors(QTextStream& s, const AbstractMetaClass* s << endl; for (QHash::const_iterator it = arg_map.cbegin(), end = arg_map.cend(); it != end; ++it) { - Indentation indentation(INDENT); + Indentation indentation(INDENT, 2); writeParameterType(s, cppClass, it.value()); } @@ -1910,7 +1935,7 @@ bool QtDocGenerator::writeInjectDocumentation(QTextStream& s, return didSomething; } -void QtDocGenerator::writeFunctionSignature(QTextStream& s, const AbstractMetaClass* cppClass, const AbstractMetaFunction* func) +QString QtDocGenerator::functionSignature(const AbstractMetaClass* cppClass, const AbstractMetaFunction* func) { QString className; if (!func->isConstructor()) @@ -1922,7 +1947,8 @@ void QtDocGenerator::writeFunctionSignature(QTextStream& s, const AbstractMetaCl if (!funcName.startsWith(className)) funcName = className + funcName; - s << funcName << "(" << parseArgDocStyle(cppClass, func) << ")"; + return funcName + QLatin1Char('(') + parseArgDocStyle(cppClass, func) + + QLatin1Char(')'); } QString QtDocGenerator::translateToPythonType(const AbstractMetaType* type, const AbstractMetaClass* cppClass) @@ -1976,8 +2002,6 @@ void QtDocGenerator::writeParameterType(QTextStream& s, const AbstractMetaClass* void QtDocGenerator::writeFunctionParametersType(QTextStream &s, const AbstractMetaClass *cppClass, const AbstractMetaFunction *func) { - Indentation indentation(INDENT); - s << endl; const AbstractMetaArgumentList &funcArgs = func->arguments(); for (AbstractMetaArgument *arg : funcArgs) { @@ -2009,22 +2033,23 @@ void QtDocGenerator::writeFunctionParametersType(QTextStream &s, const AbstractM s << endl; } -void QtDocGenerator::writeFunction(QTextStream& s, bool writeDoc, const AbstractMetaClass* cppClass, const AbstractMetaFunction* func) +void QtDocGenerator::writeFunction(QTextStream& s, const AbstractMetaClass* cppClass, + const AbstractMetaFunction* func) { - writeFunctionSignature(s, cppClass, func); - s << endl; - - formatSince(s, "method", func->typeEntry()); + s << functionSignature(cppClass, func) << "\n\n"; - if (writeDoc) { - s << endl; + { + Indentation indentation(INDENT); writeFunctionParametersType(s, cppClass, func); - s << endl; - writeInjectDocumentation(s, TypeSystem::DocModificationPrepend, cppClass, func); - if (!writeInjectDocumentation(s, TypeSystem::DocModificationReplace, cppClass, func)) - writeFormattedText(s, func->documentation(), cppClass); - writeInjectDocumentation(s, TypeSystem::DocModificationAppend, cppClass, func); + const auto version = versionOf(func->typeEntry()); + if (!version.isNull()) + s << INDENT << rstVersionAdded(version); } + + writeInjectDocumentation(s, TypeSystem::DocModificationPrepend, cppClass, func); + if (!writeInjectDocumentation(s, TypeSystem::DocModificationReplace, cppClass, func)) + writeFormattedText(s, func->documentation(), cppClass); + writeInjectDocumentation(s, TypeSystem::DocModificationAppend, cppClass, func); } static void writeFancyToc(QTextStream& s, const QStringList& items, int cols = 4) diff --git a/sources/shiboken2/generator/qtdoc/qtdocgenerator.h b/sources/shiboken2/generator/qtdoc/qtdocgenerator.h index 5545de9a9..43345716d 100644 --- a/sources/shiboken2/generator/qtdoc/qtdocgenerator.h +++ b/sources/shiboken2/generator/qtdoc/qtdocgenerator.h @@ -239,8 +239,9 @@ private: void writeFields(QTextStream &s, const AbstractMetaClass *cppClass); void writeArguments(QTextStream &s, const AbstractMetaClass *cppClass, const AbstractMetaFunction *func); - void writeFunctionSignature(QTextStream& s, const AbstractMetaClass* cppClass, const AbstractMetaFunction* func); - void writeFunction(QTextStream& s, bool writeDoc, const AbstractMetaClass* cppClass, const AbstractMetaFunction* func); + QString functionSignature(const AbstractMetaClass* cppClass, const AbstractMetaFunction* func); + void writeFunction(QTextStream& s, const AbstractMetaClass* cppClass, + const AbstractMetaFunction* func); void writeFunctionParametersType(QTextStream &s, const AbstractMetaClass *cppClass, const AbstractMetaFunction* func); void writeFunctionList(QTextStream& s, const AbstractMetaClass* cppClass); -- cgit v1.2.3