QDoc: Make example-related warnings configurable

While processing example documentation, QDoc may emit warnings if the
example lacks a project file and/or doesn't contain any images. These
warnings are generated as a result of Qt's internal business
rules. While a case can certainly be made for their validity, this
behavior in QDoc imposes Qt's rules on external parties that use QDoc.

This change makes these warnings configurable, such that projects can
decide to opt out from getting them, by introducing the following
configuration variables:

    `examples.warnaboutmissingimages = false`
    `examples.warnaboutmissingprojectfiles = false`

This allows a project to disable these warnings according to whichever
business rules are in place, by setting the configuration value to
empty, `0`, or `false`. Any other value is considered a truthy value.

The QDoc manual is updated with information about the two new
configuration variables.

[ChangeLog][QDoc][Configuration] Two new configuration variables have
been introduced to QDoc to control whether QDoc emits warnings about
missing images or missing project files, specific to example
documentation. These warnings can now be disabled by setting
`examples.warnaboutmissingimages = false` and
`examples.warnaboutmissingprojectfiles = false` in the QDoc
configuration file(s).

Fixes: QTBUG-128910
Change-Id: I3093f97c8328ebba49ed6fe219ba571b6bdaa575
Reviewed-by: Topi Reiniö <[email protected]>

Author: paulwicking

src/qdoc/qdoc/doc/qdoc-manual-qdocconf.qdoc

@@ -146,6 +146,8 @@
     \li \l {examples-variable} {examples}
     \li \l {examplesinstallpath-variable} {examplesinstallpath}
     \li \l {examples.fileextensions-variable} {examples.fileextensions}
+    \li \l {examples.warnaboutmissingimages-variable} {examples.warnaboutmissingimages}
+    \li \l {examples.warnaboutmissingprojectfiles-variable} {examples.warnaboutmissingprojectfiles}
     \li \l {excludedirs-variable} {excludedirs}
     \li \l {excludefiles-variable} {excludefiles}
     \li \l {extraimages-variable} {extraimages}
@@ -477,6 +479,34 @@
 
     See also \l{headers.fileextensions}.
 
+    \target examples.warnaboutmissingimages-variable
+    \section1 examples.warnaboutmissingimages
+
+    While processing example documentation, QDoc may emit warnings if an example
+    doesn't contain any images. This warning can be disabled by setting the
+    following configuration variable in the .qdocconf file for the project:
+
+    \c {examples.warnaboutmissingimages = false}
+
+    This configuration variable was introduced to QDoc with Qt 6.9.
+
+    See also \l{examples.warnaboutmissingprojectfiles-variable}
+    {examples.warnaboutmissingprojectfiles}.
+
+    \target examples.warnaboutmissingprojectfiles-variable
+    \section1 examples.warnaboutmissingprojectfiles
+
+    While processing example documentation, QDoc may emit warnings if an example
+    doesn't contain a project file. This warning can be disabled by setting the
+    following configuration variable in the .qdocconf file for the project:
+
+    \c {examples.warnaboutmissingprojectfiles = false}
+
+    This configuration variable was introduced to QDoc with Qt 6.9.
+
+    See also \l{examples.warnaboutmissingimages-variable}
+    {examples.warnaboutmissingimages}.
+
     \target excludedirs-variable
     \section1 excludedirs
 

src/qdoc/qdoc/src/qdoc/config.cpp

@@ -89,6 +89,8 @@ QString ConfigStrings::FILEEXTENSIONS = QStringLiteral("fileextensions");
 QString ConfigStrings::IMAGEEXTENSIONS = QStringLiteral("imageextensions");
 QString ConfigStrings::QMLTYPESPAGE = QStringLiteral("qmltypespage");
 QString ConfigStrings::QMLTYPESTITLE = QStringLiteral("qmltypestitle");
+QString ConfigStrings::WARNABOUTMISSINGIMAGES = QStringLiteral("warnaboutmissingimages");
+QString ConfigStrings::WARNABOUTMISSINGPROJECTFILES = QStringLiteral("warnaboutmissingprojectfiles");
 QString ConfigStrings::WARNINGLIMIT = QStringLiteral("warninglimit");
 
 /*!
@@ -370,6 +372,8 @@ void Config::reset()
     setStringList(CONFIG_OUTPUTFORMATS, QStringList("HTML"));
     setStringList(CONFIG_TABSIZE, QStringList("8"));
     setStringList(CONFIG_LOCATIONINFO, QStringList("true"));
+    setStringList(CONFIG_WARNABOUTMISSINGIMAGES, QStringList("true"));
+    setStringList(CONFIG_WARNABOUTMISSINGPROJECTFILES, QStringList("true"));
 
     // Publish options from the command line as config variables
     const auto setListFlag = [this](const QString &key, bool test) {

src/qdoc/qdoc/src/qdoc/config.h

@@ -315,6 +315,8 @@ struct ConfigStrings
     static QString IMAGEEXTENSIONS;
     static QString QMLTYPESPAGE;
     static QString QMLTYPESTITLE;
+    static QString WARNABOUTMISSINGIMAGES;
+    static QString WARNABOUTMISSINGPROJECTFILES;
     static QString WARNINGLIMIT;
 };
 
@@ -393,6 +395,8 @@ struct ConfigStrings
 #define CONFIG_IMAGEEXTENSIONS ConfigStrings::IMAGEEXTENSIONS
 #define CONFIG_QMLTYPESPAGE ConfigStrings::QMLTYPESPAGE
 #define CONFIG_QMLTYPESTITLE ConfigStrings::QMLTYPESTITLE
+#define CONFIG_WARNABOUTMISSINGIMAGES ConfigStrings::WARNABOUTMISSINGIMAGES
+#define CONFIG_WARNABOUTMISSINGPROJECTFILES ConfigStrings::WARNABOUTMISSINGPROJECTFILES
 #define CONFIG_WARNINGLIMIT ConfigStrings::WARNINGLIMIT
 
 inline bool Config::singleExec() const

src/qdoc/qdoc/src/qdoc/manifestwriter.cpp

@@ -23,10 +23,18 @@ QT_BEGIN_NAMESPACE
 void warnAboutUnusedAttributes(const QStringList &usedAttributes, const ExampleNode *example)
 {
     QMap<QString, QString> attributesToWarnFor;
-    attributesToWarnFor.insert(QStringLiteral("imageUrl"),
-            QStringLiteral("Example documentation should have at least one '\\image'"));
-    attributesToWarnFor.insert(QStringLiteral("projectPath"),
-            QStringLiteral("Example has no project file"));
+    bool missingImageWarning = Config::instance().get(CONFIG_EXAMPLES + Config::dot + CONFIG_WARNABOUTMISSINGIMAGES).asBool();
+    bool missingProjectFileWarning = Config::instance().get(CONFIG_EXAMPLES + Config::dot + CONFIG_WARNABOUTMISSINGPROJECTFILES).asBool();
+
+    if (missingImageWarning)
+        attributesToWarnFor.insert(QStringLiteral("imageUrl"),
+                QStringLiteral("Example documentation should have at least one '\\image'"));
+    if (missingProjectFileWarning)
+        attributesToWarnFor.insert(QStringLiteral("projectPath"),
+                QStringLiteral("Example has no project file"));
+
+    if (attributesToWarnFor.empty())
+        return;
 
     for (auto it = attributesToWarnFor.cbegin(); it != attributesToWarnFor.cend(); ++it) {
         if (!usedAttributes.contains(it.key()))