diff --git a/src/tools/qdoc/config.cpp b/src/tools/qdoc/config.cpp index 4842c68c92..beb0bae291 100644 --- a/src/tools/qdoc/config.cpp +++ b/src/tools/qdoc/config.cpp @@ -91,6 +91,7 @@ QString ConfigStrings::OUTPUTENCODING = QStringLiteral("outputencoding"); QString ConfigStrings::OUTPUTLANGUAGE = QStringLiteral("outputlanguage"); QString ConfigStrings::OUTPUTFORMATS = QStringLiteral("outputformats"); QString ConfigStrings::OUTPUTPREFIXES = QStringLiteral("outputprefixes"); +QString ConfigStrings::OUTPUTSUFFIXES = QStringLiteral("outputsuffixes"); QString ConfigStrings::PROJECT = QStringLiteral("project"); QString ConfigStrings::REDIRECTDOCUMENTATIONTODEVNULL = QStringLiteral("redirectdocumentationtodevnull"); QString ConfigStrings::QHP = QStringLiteral("qhp"); diff --git a/src/tools/qdoc/config.h b/src/tools/qdoc/config.h index 802bcf929d..8d6a124bd1 100644 --- a/src/tools/qdoc/config.h +++ b/src/tools/qdoc/config.h @@ -203,6 +203,7 @@ struct ConfigStrings static QString OUTPUTLANGUAGE; static QString OUTPUTFORMATS; static QString OUTPUTPREFIXES; + static QString OUTPUTSUFFIXES; static QString PROJECT; static QString REDIRECTDOCUMENTATIONTODEVNULL; static QString QHP; @@ -278,6 +279,7 @@ struct ConfigStrings #define CONFIG_OUTPUTLANGUAGE ConfigStrings::OUTPUTLANGUAGE #define CONFIG_OUTPUTFORMATS ConfigStrings::OUTPUTFORMATS #define CONFIG_OUTPUTPREFIXES ConfigStrings::OUTPUTPREFIXES +#define CONFIG_OUTPUTSUFFIXES ConfigStrings::OUTPUTSUFFIXES #define CONFIG_PROJECT ConfigStrings::PROJECT #define CONFIG_REDIRECTDOCUMENTATIONTODEVNULL ConfigStrings::REDIRECTDOCUMENTATIONTODEVNULL #define CONFIG_QHP ConfigStrings::QHP diff --git a/src/tools/qdoc/doc/qdoc-manual-qdocconf.qdoc b/src/tools/qdoc/doc/qdoc-manual-qdocconf.qdoc index 226c107e3a..40576a1da0 100644 --- a/src/tools/qdoc/doc/qdoc-manual-qdocconf.qdoc +++ b/src/tools/qdoc/doc/qdoc-manual-qdocconf.qdoc @@ -113,6 +113,8 @@ \li \l {manifestmeta-variable} {manifestmeta} \li \l {outputdir-variable} {outputdir} \li \l {outputformats-variable} {outputformats} + \li \l {outputprefixes-variable} {outputprefixes} + \li \l {outputsuffixes-variable} {outputsuffixes} \li \l {sourcedirs-variable} {sourcedirs} \li \l {sources-variable} {sources} \li \l {sources.fileextensions-variable} {sources.fileextensions} @@ -814,21 +816,48 @@ Currently, QDoc only supports the HTML format. It is also the default format, and doesn't need to be specified. - \target outputprefixes + \target outputprefixes-variable \section1 outputprefixes The \c outputprefixes variable specifies a mapping between types of files and the prefixes to prepend to the HTML file names in the generated documentation. - \code - outputprefixes = QML + \badcode + outputprefixes = QML JS outputprefixes.QML = uicomponents- + outputprefixes.JS = uicomponents- \endcode By default, files containing the API documentation for QML types - are prefixed with "qml-". In the above example, the - prefix \c "uicomponents" is used instead. + are prefixed with "qml-", and javaScript types with "js-". In the + above example, the prefix \c "uicomponents" is used instead for + both. + + The output prefix is applied to file names for documentation on + QML and JS types. + + \target outputsuffixes-variable + \section1 outputsuffixes + + The \c outputsuffixes variable specifies a mapping between types of + files and module name suffixes to append to the HTML file names. + + \badcode + outputsuffixes = QML + outputsuffixes.QML = -tp + \endcode + + Given a QML module name \e FooBar and the default + \l {outputprefixes-variable}{output prefix} ("qml-"), the file name of + the generated HTML page for a QML type \e FooWidget would be + \c qml-foobar-tp-foowidget.html. + + By default, no suffix is used. The output suffix, if defined, is applied + to file names for documentation on QML and JS types, and their respective + module pages. + + The \c outputsuffixes variable was introduced in QDoc 5.6. \target qhp-variable \section1 qhp diff --git a/src/tools/qdoc/generator.cpp b/src/tools/qdoc/generator.cpp index 831d975591..9f722abe9b 100644 --- a/src/tools/qdoc/generator.cpp +++ b/src/tools/qdoc/generator.cpp @@ -63,6 +63,7 @@ QString Generator::outSubdir_; QStringList Generator::outFileNames_; QSet Generator::outputFormats; QHash Generator::outputPrefixes; +QHash Generator::outputSuffixes; QString Generator::project_; QStringList Generator::scriptDirs; QStringList Generator::scriptFiles; @@ -329,21 +330,21 @@ QString Generator::fileBase(const Node *node) const else if (node->isQmlType() || node->isQmlBasicType() || node->isJsType() || node->isJsBasicType()) { base = node->name(); - if (!node->logicalModuleName().isEmpty()) { - base.prepend(node->logicalModuleName() + QLatin1Char('-')); - } /* To avoid file name conflicts in the html directory, - we prepend a prefix (by default, "qml-") to the file name of QML - element doc files. + we prepend a prefix (by default, "qml-") and an optional suffix + to the file name. The suffix, if one exists, is appended to the + module name. */ - if (node->isQmlType() || node->isQmlBasicType()) - base.prepend(outputPrefix(QLatin1String("QML"))); - else - base.prepend(outputPrefix(QLatin1String("JS"))); + if (!node->logicalModuleName().isEmpty()) { + base.prepend(node->logicalModuleName() + + outputSuffix(node) + + QLatin1Char('-')); + } + base.prepend(outputPrefix(node)); } else if (node->isCollectionNode()) { - base = node->name(); + base = node->name() + outputSuffix(node); if (base.endsWith(".html")) base.truncate(base.length() - 5); @@ -356,7 +357,7 @@ QString Generator::fileBase(const Node *node) const else if (node->isModule()) { base.append("-module"); } - // Why not add "-group" for gropup pages? + // Why not add "-group" for group pages? } else { const Node *p = node; @@ -519,9 +520,7 @@ QString Generator::fullDocumentLocation(const Node *node, bool useSubdir) else if (node->isQmlType() || node->isQmlBasicType() || node->isJsType() || node->isJsBasicType()) { QString fb = fileBase(node); - if (fb.startsWith(Generator::outputPrefix(QLatin1String("QML")))) - return fb + QLatin1Char('.') + currentGenerator()->fileExtension(); - else if (fb.startsWith(Generator::outputPrefix(QLatin1String("JS")))) + if (fb.startsWith(outputPrefix(node))) return fb + QLatin1Char('.') + currentGenerator()->fileExtension(); else { QString mq; @@ -529,10 +528,7 @@ QString Generator::fullDocumentLocation(const Node *node, bool useSubdir) mq = node->logicalModuleName().replace(QChar('.'),QChar('-')); mq = mq.toLower() + QLatin1Char('-'); } - QLatin1String prefix = QLatin1String("QML"); - if (node->isJsType() || node->isJsBasicType()) - prefix = QLatin1String("JS"); - return fdl+ Generator::outputPrefix(prefix) + mq + fileBase(node) + + return fdl + outputPrefix(node) + mq + fileBase(node) + QLatin1Char('.') + currentGenerator()->fileExtension(); } } @@ -1804,15 +1800,24 @@ void Generator::initialize(const Config &config) project_ = config.getString(CONFIG_PROJECT); - QStringList prefixes = config.getStringList(CONFIG_OUTPUTPREFIXES); - if (!prefixes.isEmpty()) { - foreach (const QString &prefix, prefixes) + outputPrefixes.clear(); + QStringList items = config.getStringList(CONFIG_OUTPUTPREFIXES); + if (!items.isEmpty()) { + foreach (const QString &prefix, items) outputPrefixes[prefix] = config.getString(CONFIG_OUTPUTPREFIXES + Config::dot + prefix); } else { outputPrefixes[QLatin1String("QML")] = QLatin1String("qml-"); outputPrefixes[QLatin1String("JS")] = QLatin1String("js-"); } + + outputSuffixes.clear(); + items = config.getStringList(CONFIG_OUTPUTSUFFIXES); + if (!items.isEmpty()) { + foreach (const QString &suffix, items) + outputSuffixes[suffix] = config.getString(CONFIG_OUTPUTSUFFIXES + Config::dot + suffix); + } + noLinkErrors_ = config.getBool(CONFIG_NOLINKERRORS); autolinkErrors_ = config.getBool(CONFIG_AUTOLINKERRORS); } @@ -1862,9 +1867,25 @@ QString Generator::outFileName() return QFileInfo(static_cast(out().device())->fileName()).fileName(); } -QString Generator::outputPrefix(const QString &nodeType) +QString Generator::outputPrefix(const Node *node) { - return outputPrefixes[nodeType]; + // Prefix is applied to QML and JS types + if (node->isQmlType() || node->isQmlBasicType()) + return outputPrefixes[QLatin1String("QML")]; + if (node->isJsType() || node->isJsBasicType()) + return outputPrefixes[QLatin1String("JS")]; + return QString(); +} + +QString Generator::outputSuffix(const Node *node) +{ + // Suffix is applied to QML and JS types, as + // well as module pages. + if (node->isQmlModule() || node->isQmlType() || node->isQmlBasicType()) + return outputSuffixes[QLatin1String("QML")]; + if (node->isJsModule() || node->isJsType() || node->isJsBasicType()) + return outputSuffixes[QLatin1String("JS")]; + return QString(); } bool Generator::parseArg(const QString& src, diff --git a/src/tools/qdoc/generator.h b/src/tools/qdoc/generator.h index e4bcd29e52..6c44cd189c 100644 --- a/src/tools/qdoc/generator.h +++ b/src/tools/qdoc/generator.h @@ -135,7 +135,8 @@ protected: virtual QString typeString(const Node *node); static bool matchAhead(const Atom *atom, Atom::AtomType expectedAtomType); - static QString outputPrefix(const QString &nodeType); + static QString outputPrefix(const Node* node); + static QString outputSuffix(const Node* node); static void singularPlural(Text& text, const NodeList& nodes); static void supplementAlsoList(const Node *node, QList &alsoList); static QString trimmedTrailing(const QString &string); @@ -214,6 +215,7 @@ private: static QStringList outFileNames_; static QSet outputFormats; static QHash outputPrefixes; + static QHash outputSuffixes; static QStringList scriptDirs; static QStringList scriptFiles; static QStringList styleDirs;