qdoc: Add styling for \note, \important and \warning

And add Atom types for Warning instead of simply hard-coding a bold
warning note.

Fix a compiler warning for tst_generatedoutput in passing.

Pick-to: 6.2 5.15
Fixes: QTBUG-97448
Change-Id: I1fe691ffaadc549b17c8628817fe761d3be0fad7
Reviewed-by: Paul Wicking <paul.wicking@qt.io>

12 files changed, 54 insertions, 29 deletions

diff --git a/src/qdoc/atom.cpp b/src/qdoc/atom.cpp
index 2844e8b33..eafaac764 100644
--- a/src/qdoc/atom.cpp
+++ b/src/qdoc/atom.cpp
@@ -233,6 +233,8 @@ static const struct
              { "TableOfContents", Atom::TableOfContents },
              { "Target", Atom::Target },
              { "UnhandledFormat", Atom::UnhandledFormat },
+             { "WarningLeft", Atom::WarningLeft },
+             { "WarningRight", Atom::WarningRight },
              { "UnknownCommand", Atom::UnknownCommand },
              { nullptr, 0 } };
 
diff --git a/src/qdoc/atom.h b/src/qdoc/atom.h
index 77a058a70..544e8369b 100644
--- a/src/qdoc/atom.h
+++ b/src/qdoc/atom.h
@@ -128,6 +128,8 @@ public:
         TableOfContents,
         Target,
         UnhandledFormat,
+        WarningLeft,
+        WarningRight,
         UnknownCommand,
         Last = UnknownCommand
     };
diff --git a/src/qdoc/docbookgenerator.cpp b/src/qdoc/docbookgenerator.cpp
index d4ee9374f..2318cb963 100644
--- a/src/qdoc/docbookgenerator.cpp
+++ b/src/qdoc/docbookgenerator.cpp
@@ -494,14 +494,18 @@ qsizetype DocBookGenerator::generateAtom(const Atom *atom, const Node *relative)
     case Atom::ImageText:
         break;
     case Atom::ImportantLeft:
-    case Atom::NoteLeft: {
-        QString tag = atom->type() == Atom::ImportantLeft ? "important" : "note";
-        m_writer->writeStartElement(dbNamespace, tag);
+    case Atom::NoteLeft:
+    case Atom::WarningLeft: {
+        QString admonType = atom->typeString().toLower();
+        // Remove 'Left' to get the admonition type
+        admonType.chop(4);
+        m_writer->writeStartElement(dbNamespace, admonType);
         newLine();
         m_writer->writeStartElement(dbNamespace, "para");
     } break;
     case Atom::ImportantRight:
     case Atom::NoteRight:
+    case Atom::WarningRight:
         m_writer->writeEndElement(); // para
         newLine();
         m_writer->writeEndElement(); // note/important
diff --git a/src/qdoc/docparser.cpp b/src/qdoc/docparser.cpp
index 814c5fee6..1294f5d7a 100644
--- a/src/qdoc/docparser.cpp
+++ b/src/qdoc/docparser.cpp
@@ -1078,11 +1078,7 @@ void DocParser::parse(const QString &source, DocPrivate *docPrivate,
                     break;
                 case CMD_WARNING:
                     leavePara();
-                    enterPara();
-                    append(Atom::FormattingLeft, ATOM_FORMATTING_BOLD);
-                    append(Atom::String, "Warning:");
-                    append(Atom::FormattingRight, ATOM_FORMATTING_BOLD);
-                    append(Atom::String, " ");
+                    enterPara(Atom::WarningLeft, Atom::WarningRight);
                     break;
                 case CMD_OVERLOAD:
                     m_private->m_metacommandsUsed.insert(cmdStr);
diff --git a/src/qdoc/htmlgenerator.cpp b/src/qdoc/htmlgenerator.cpp
index ba273c490..ccde100f8 100644
--- a/src/qdoc/htmlgenerator.cpp
+++ b/src/qdoc/htmlgenerator.cpp
@@ -644,23 +644,24 @@ qsizetype HtmlGenerator::generateAtom(const Atom *atom, const Node *relative, Co
     } break;
     case Atom::ImageText:
         break;
+    // Admonitions
     case Atom::ImportantLeft:
-        out() << "<p>";
-        out() << formattingLeftMap()[ATOM_FORMATTING_BOLD];
-        out() << "Important: ";
-        out() << formattingRightMap()[ATOM_FORMATTING_BOLD];
-        break;
-    case Atom::ImportantRight:
-        out() << "</p>";
-        break;
     case Atom::NoteLeft:
-        out() << "<p>";
+    case Atom::WarningLeft: {
+        QString admonType = atom->typeString();
+        // Remove 'Left' from atom type to get the admonition type
+        admonType.chop(4);
+        out() << "<div class=\"admonition " << admonType.toLower() << "\">\n"
+              << "<p>";
         out() << formattingLeftMap()[ATOM_FORMATTING_BOLD];
-        out() << "Note: ";
+        out() << admonType << ": ";
         out() << formattingRightMap()[ATOM_FORMATTING_BOLD];
-        break;
+    } break;
+    case Atom::ImportantRight:
     case Atom::NoteRight:
-        out() << "</p>\n";
+    case Atom::WarningRight:
+        out() << "</p>\n"
+              << "</div>\n";
         break;
     case Atom::LegaleseLeft:
         out() << "<div class=\"LegaleseLeft\">";
diff --git a/src/qdoc/webxmlgenerator.cpp b/src/qdoc/webxmlgenerator.cpp
index 29a74754a..2f8f772b5 100644
--- a/src/qdoc/webxmlgenerator.cpp
+++ b/src/qdoc/webxmlgenerator.cpp
@@ -532,10 +532,6 @@ const Atom *WebXMLGenerator::addAtomElements(QXmlStreamWriter &writer, const Ato
         writer.writeCharacters(" ");
         break;
 
-    case Atom::ImportantRight:
-        writer.writeEndElement(); // para
-        break;
-
     case Atom::LegaleseLeft:
         writer.writeStartElement("legalese");
         break;
@@ -612,7 +608,10 @@ const Atom *WebXMLGenerator::addAtomElements(QXmlStreamWriter &writer, const Ato
         writer.writeCharacters(" ");
         break;
 
+    // End admonition elements
+    case Atom::ImportantRight:
     case Atom::NoteRight:
+    case Atom::WarningRight:
         writer.writeEndElement(); // para
         break;
 
@@ -737,6 +736,12 @@ const Atom *WebXMLGenerator::addAtomElements(QXmlStreamWriter &writer, const Ato
         writer.writeEndElement();
         break;
 
+    case Atom::WarningLeft:
+        writer.writeStartElement("para");
+        writer.writeTextElement("bold", "Warning:");
+        writer.writeCharacters(" ");
+        break;
+
     case Atom::UnhandledFormat:
     case Atom::UnknownCommand:
         writer.writeCharacters(atom->typeString());
diff --git a/tests/auto/qdoc/generatedoutput/expected_output/docbook/qdoctests-qdocfileoutput-exhaustive.xml b/tests/auto/qdoc/generatedoutput/expected_output/docbook/qdoctests-qdocfileoutput-exhaustive.xml
index af2fdd955..7d9ed16f0 100644
--- a/tests/auto/qdoc/generatedoutput/expected_output/docbook/qdoctests-qdocfileoutput-exhaustive.xml
+++ b/tests/auto/qdoc/generatedoutput/expected_output/docbook/qdoctests-qdocfileoutput-exhaustive.xml
@@ -57,7 +57,9 @@
 <db:note>
 <db:para>The code above doesn't compile</db:para>
 </db:note>
-<db:para><db:emphasis role="bold">Warning:</db:emphasis> The following commands have yet to be tested: footnote link sincelist header index topicref // or just don’t care, remove it image inlineimage printline printto printuntil // what’s the difference between printto and printuntil??? quotefile quotefromfile quotefunction skipline skipto skipuntil span snippet codeline overload sub sup tableofcontents tt uicontrol endmapref endomit underline unicode</db:para>
+<db:warning>
+<db:para>The following commands have yet to be tested: footnote link sincelist header index topicref // or just don’t care, remove it image inlineimage printline printto printuntil // what’s the difference between printto and printuntil??? quotefile quotefromfile quotefunction skipline skipto skipuntil span snippet codeline overload sub sup tableofcontents tt uicontrol endmapref endomit underline unicode</db:para>
+</db:warning>
 </db:section>
 </db:section>
 </db:section>
diff --git a/tests/auto/qdoc/generatedoutput/expected_output/nestedmacro/testcpp-module.html b/tests/auto/qdoc/generatedoutput/expected_output/nestedmacro/testcpp-module.html
index f3de1542a..4bc14d345 100644
--- a/tests/auto/qdoc/generatedoutput/expected_output/nestedmacro/testcpp-module.html
+++ b/tests/auto/qdoc/generatedoutput/expected_output/nestedmacro/testcpp-module.html
@@ -33,7 +33,9 @@
 <!-- $$$TestCPP-description -->
 <div class="descr">
 <h2 id="details">Detailed Description</h2>
+<div class="admonition note">
 <p><b>Note: </b>This is just a test.</p>
+</div>
 <p><b>This module was introduced in version 5.15.</b></p>
 </div>
 <!-- @@@TestCPP -->
diff --git a/tests/auto/qdoc/generatedoutput/expected_output/noautolist/testcpp-module.html b/tests/auto/qdoc/generatedoutput/expected_output/noautolist/testcpp-module.html
index fd5beda6d..6db15ca22 100644
--- a/tests/auto/qdoc/generatedoutput/expected_output/noautolist/testcpp-module.html
+++ b/tests/auto/qdoc/generatedoutput/expected_output/noautolist/testcpp-module.html
@@ -21,8 +21,10 @@
 <!-- $$$TestCPP-description -->
 <div class="descr">
 <h2 id="details">Detailed Description</h2>
+<div class="admonition note">
 <p><b>Note: </b>This is just a test.</p>
 </div>
+</div>
 <!-- @@@TestCPP -->
 </body>
 </html>
diff --git a/tests/auto/qdoc/generatedoutput/expected_output/qdoctests-qdocfileoutput-exhaustive.html b/tests/auto/qdoc/generatedoutput/expected_output/qdoctests-qdocfileoutput-exhaustive.html
index 508c12398..cbf7d6894 100644
--- a/tests/auto/qdoc/generatedoutput/expected_output/qdoctests-qdocfileoutput-exhaustive.html
+++ b/tests/auto/qdoc/generatedoutput/expected_output/qdoctests-qdocfileoutput-exhaustive.html
@@ -42,13 +42,20 @@
  <tr valign="top" class="odd"><td >Table item in a table row</td></tr>
 <tr valign="top" class="even"><td >Another item in a different row</td></tr>
 </table></div>
-<p><b>Important: </b>This is really important.</p><p>For example, if you have code like</p>
+<div class="admonition important">
+<p><b>Important: </b>This is really important.</p>
+</div>
+<p>For example, if you have code like</p>
 <pre class="cpp plain">This is old code.</pre>
 <p>you can rewrite it as</p>
 <pre class="cpp">This is <span class="keyword">new</span> and shiny<span class="operator">!</span></pre>
+<div class="admonition note">
 <p><b>Note: </b>The code above doesn't compile</p>
+</div>
 <hr />
-<p><b>Warning:</b> The following commands have yet to be tested: footnote link sincelist header index topicref // or just don’t care, remove it image inlineimage printline printto printuntil // what’s the difference between printto and printuntil??? quotefile quotefromfile quotefunction skipline skipto skipuntil span snippet codeline overload sub sup tableofcontents tt uicontrol endmapref endomit underline unicode</p>
+<div class="admonition warning">
+<p><b>Warning: </b>The following commands have yet to be tested: footnote link sincelist header index topicref // or just don’t care, remove it image inlineimage printline printto printuntil // what’s the difference between printto and printuntil??? quotefile quotefromfile quotefunction skipline skipto skipuntil span snippet codeline overload sub sup tableofcontents tt uicontrol endmapref endomit underline unicode</p>
+</div>
 </div>
 <!-- @@@qdoctests-qdocfileoutput-exhaustive.html -->
 </body>
diff --git a/tests/auto/qdoc/generatedoutput/expected_output/testcpp-module.html b/tests/auto/qdoc/generatedoutput/expected_output/testcpp-module.html
index 117f34d72..04bd8e487 100644
--- a/tests/auto/qdoc/generatedoutput/expected_output/testcpp-module.html
+++ b/tests/auto/qdoc/generatedoutput/expected_output/testcpp-module.html
@@ -33,8 +33,10 @@
 <!-- $$$TestCPP-description -->
 <div class="descr">
 <h2 id="details">Detailed Description</h2>
+<div class="admonition note">
 <p><b>Note: </b>This is just a test.</p>
 </div>
+</div>
 <!-- @@@TestCPP -->
 </body>
 </html>
diff --git a/tests/auto/qdoc/generatedoutput/tst_generatedoutput.cpp b/tests/auto/qdoc/generatedoutput/tst_generatedoutput.cpp
index 7473546b9..ccb131222 100644
--- a/tests/auto/qdoc/generatedoutput/tst_generatedoutput.cpp
+++ b/tests/auto/qdoc/generatedoutput/tst_generatedoutput.cpp
@@ -105,8 +105,8 @@ void tst_generatedOutput::initTestCase()
     // Resolve the path to the file containing extra parameters
     m_extraParams = QFileInfo(QTest::currentAppName()).dir().filePath("qdocincludepaths.inc");
     if (!QFileInfo::exists(m_extraParams)) {
-        const QString warningMessage = "Cannot locate " + m_extraParams;
-        qWarning(qPrintable(warningMessage));
+        qWarning().nospace() << QStringLiteral("Cannot locate")
+                             << qUtf8Printable(m_extraParams);
         m_extraParams.clear();
     } else {
         m_extraParams.insert(0, '@');