summaryrefslogtreecommitdiffstats
diff options
authorPaul Wicking <paul.wicking@qt.io>2025-05-08 10:12:03 +0200
committerPaul Wicking <paul.wicking@qt.io>2025-05-09 11:12:04 +0200
commitfd37afd39f6a589f90e827b585b13a0afb5196d2 (patch)
tree54efd1912a54a0d89f32378b9d2725dc2f9e5225
parentf3ef3cff765082f439cd1a7bfb8822beaa28784a (diff)
QDoc: Differentiate overload notes from admonitions6.9
A recent change to QDoc improved QDoc's handling of the `\overload` command. However, as an unintentional consequence, overload notes are now prefixed with "Note:", and get the same visual treatment as other admonitions. This makes them appear as important or even critical information. What allowed this to happen and pass review, is identified as the API in `Generator::generateAddendum()`, which takes a boolean value as the fourth parameter. This boolean value controls the choice of CSS class and generation of the "Note:" prefix. An overload that only takes three parameters and unconditionally passes `true` for the boolean allowed the issue to sneak in. This change introduces an `AdmonitionPrefix` enum to replace the boolean parameter that controlled prefix display. The overload is modified to pass `AdmonitionPrefix::Note`, such that the original behavior is kept for calls to the function version that takes three arguments. Other call sites have been updated accordingly. As a result, overload notes now appear without the "Note:" prefix while maintaining their informational content. Test data is updated to reflect the new behavior. Pick-to: 6.8 6.9.1 Task-number: QTBUG-136532 Change-Id: I39b923d6a4079079d5071136f13273032f279029 Reviewed-by: Topi Reiniƶ <topi.reinio@qt.io> (cherry picked from commit 7031d090fe0e2620de1e984dad6cba7682a477d3)
-rw-r--r--src/qdoc/qdoc/src/qdoc/docbookgenerator.cpp26
-rw-r--r--src/qdoc/qdoc/src/qdoc/docbookgenerator.h2
-rw-r--r--src/qdoc/qdoc/src/qdoc/generator.cpp17
-rw-r--r--src/qdoc/qdoc/src/qdoc/generator.h10
-rw-r--r--src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/overload_command/expected/testclass.html4
5 files changed, 38 insertions, 21 deletions
diff --git a/src/qdoc/qdoc/src/qdoc/docbookgenerator.cpp b/src/qdoc/qdoc/src/qdoc/docbookgenerator.cpp
index cb0002936..87c3ccd62 100644
--- a/src/qdoc/qdoc/src/qdoc/docbookgenerator.cpp
+++ b/src/qdoc/qdoc/src/qdoc/docbookgenerator.cpp
@@ -2676,7 +2676,7 @@ void DocBookGenerator::generateBody(const Node *node)
generateReimplementsClause(fn);
else if (node->isProperty()) {
if (static_cast<const PropertyNode *>(node)->propertyType() != PropertyNode::PropertyType::StandardProperty)
- generateAddendum(node, BindableProperty, nullptr, false);
+ generateAddendum(node, BindableProperty, nullptr, AdmonitionPrefix::None);
}
// Generate the body.
@@ -2688,13 +2688,13 @@ void DocBookGenerator::generateBody(const Node *node)
// Output what is after the main body.
if (fn) {
if (fn->isQmlSignal())
- generateAddendum(node, QmlSignalHandler, nullptr, true);
+ generateAddendum(node, QmlSignalHandler, nullptr, AdmonitionPrefix::Note);
if (fn->isPrivateSignal())
- generateAddendum(node, PrivateSignal, nullptr, true);
+ generateAddendum(node, PrivateSignal, nullptr, AdmonitionPrefix::Note);
if (fn->isInvokable())
- generateAddendum(node, Invokable, nullptr, true);
+ generateAddendum(node, Invokable, nullptr, AdmonitionPrefix::Note);
if (fn->hasAssociatedProperties())
- generateAddendum(node, AssociatedProperties, nullptr, true);
+ generateAddendum(node, AssociatedProperties, nullptr, AdmonitionPrefix::Note);
}
// Warning generation skipped with respect to Generator::generateBody.
@@ -3994,13 +3994,19 @@ void DocBookGenerator::generateOverloadedSignal(const Node *node)
is unused in this generator.
*/
void DocBookGenerator::generateAddendum(const Node *node, Addendum type, CodeMarker *marker,
- bool generateNote)
+ AdmonitionPrefix prefix)
{
Q_UNUSED(marker)
Q_ASSERT(node && !node->name().isEmpty());
- if (generateNote) {
+
+ switch (prefix) {
+ case AdmonitionPrefix::None:
+ break;
+ case AdmonitionPrefix::Note: {
m_writer->writeStartElement(dbNamespace, "note");
newLine();
+ break;
+ }
}
switch (type) {
case Invokable:
@@ -4086,7 +4092,7 @@ void DocBookGenerator::generateAddendum(const Node *node, Addendum type, CodeMar
break;
}
- if (generateNote) {
+ if (prefix == AdmonitionPrefix::Note) {
m_writer->writeEndElement(); // note
newLine();
}
@@ -4291,9 +4297,9 @@ void DocBookGenerator::generateSectionList(const Section &section, const Node *r
newLine();
if (hasPrivateSignals)
- generateAddendum(relative, Generator::PrivateSignal, nullptr, true);
+ generateAddendum(relative, Generator::PrivateSignal, nullptr, AdmonitionPrefix::Note);
if (isInvokable)
- generateAddendum(relative, Generator::Invokable, nullptr, true);
+ generateAddendum(relative, Generator::Invokable, nullptr, AdmonitionPrefix::Note);
}
if (!useObsoleteMembers && section.style() == Section::Summary
diff --git a/src/qdoc/qdoc/src/qdoc/docbookgenerator.h b/src/qdoc/qdoc/src/qdoc/docbookgenerator.h
index 2d18cf5d7..37cbf80b4 100644
--- a/src/qdoc/qdoc/src/qdoc/docbookgenerator.h
+++ b/src/qdoc/qdoc/src/qdoc/docbookgenerator.h
@@ -59,7 +59,7 @@ protected:
bool generateThreadSafeness(const Node *node);
bool generateSince(const Node *node);
void generateAddendum(const Node *node, Generator::Addendum type, CodeMarker *marker,
- bool generateNote) override;
+ AdmonitionPrefix prefix) override;
using Generator::generateBody;
void generateBody(const Node *node);
diff --git a/src/qdoc/qdoc/src/qdoc/generator.cpp b/src/qdoc/qdoc/src/qdoc/generator.cpp
index 764e73cdb..6e076d8c1 100644
--- a/src/qdoc/qdoc/src/qdoc/generator.cpp
+++ b/src/qdoc/qdoc/src/qdoc/generator.cpp
@@ -723,7 +723,7 @@ void Generator::generateBody(const Node *node, CodeMarker *marker)
if (fn->hasAssociatedProperties())
generateAddendum(node, AssociatedProperties, marker);
if (fn->hasOverloads() && fn->doc().hasOverloadCommand())
- generateAddendum(node, OverloadNote, marker);
+ generateAddendum(node, OverloadNote, marker, AdmonitionPrefix::None);
}
// Generate warnings
@@ -1270,17 +1270,22 @@ void Generator::generateStatus(const Node *node, CodeMarker *marker)
as the code marker.
*/
void Generator::generateAddendum(const Node *node, Addendum type, CodeMarker *marker,
- bool generateNote)
+ AdmonitionPrefix prefix)
{
Q_ASSERT(node && !node->name().isEmpty());
Text text;
text << Atom(Atom::DivLeft,
- "class=\"admonition %1\""_L1.arg(generateNote ? u"note"_s : u"auto"_s));
+ "class=\"admonition %1\""_L1.arg(prefix == AdmonitionPrefix::Note ? u"note"_s : u"auto"_s));
text << Atom::ParaLeft;
- if (generateNote) {
- text << Atom(Atom::FormattingLeft, ATOM_FORMATTING_BOLD)
- << "Note: " << Atom(Atom::FormattingRight, ATOM_FORMATTING_BOLD);
+ switch (prefix) {
+ case AdmonitionPrefix::None:
+ break;
+ case AdmonitionPrefix::Note: {
+ text << Atom(Atom::FormattingLeft, ATOM_FORMATTING_BOLD)
+ << "Note: " << Atom(Atom::FormattingRight, ATOM_FORMATTING_BOLD);
+ break;
+ }
}
switch (type) {
diff --git a/src/qdoc/qdoc/src/qdoc/generator.h b/src/qdoc/qdoc/src/qdoc/generator.h
index 7de401673..087672c9e 100644
--- a/src/qdoc/qdoc/src/qdoc/generator.h
+++ b/src/qdoc/qdoc/src/qdoc/generator.h
@@ -41,6 +41,12 @@ public:
OverloadNote
};
+ enum class AdmonitionPrefix : unsigned char
+ {
+ None,
+ Note
+ };
+
Generator(FileResolver& file_resolver);
virtual ~Generator();
@@ -119,10 +125,10 @@ protected:
void generateNoexceptNote(const Node *node, CodeMarker *marker);
void generateStatus(const Node *node, CodeMarker *marker);
virtual void generateAddendum(const Node *node, Addendum type, CodeMarker *marker,
- bool generateNote);
+ AdmonitionPrefix prefix);
virtual void generateAddendum(const Node *node, Addendum type, CodeMarker *marker)
{
- generateAddendum(node, type, marker, true);
+ generateAddendum(node, type, marker, AdmonitionPrefix::Note);
};
void generateThreadSafeness(const Node *node, CodeMarker *marker);
bool generateComparisonCategory(const Node *node, CodeMarker *marker = nullptr);
diff --git a/src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/overload_command/expected/testclass.html b/src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/overload_command/expected/testclass.html
index f2b181789..493dc71b4 100644
--- a/src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/overload_command/expected/testclass.html
+++ b/src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/overload_command/expected/testclass.html
@@ -48,12 +48,12 @@
<!-- $$$another_method$$$another_methodfloat -->
<h3 class="fn" translate="no" id="another_method-1"><span class="type">void</span> TestClass::<span class="name">another_method</span>(<span class="type">float</span> <i>overloads</i>)</h3>
<p>A function that overloads another and documents it vaguely.</p>
-<div class="admonition note"><p><b>Note: </b>This is an overloaded function.</p>
+<div class="admonition auto"><p>This is an overloaded function.</p>
</div><!-- @@@another_method -->
<!-- $$$another_method$$$another_methodint -->
<h3 class="fn" translate="no" id="another_method-2"><span class="type">void</span> TestClass::<span class="name">another_method</span>(<span class="type">int</span> <i>number</i>)</h3>
<p>A function that overloads another and correctly documents it.</p>
-<div class="admonition note"><p><b>Note: </b>This function overloads <a href="testclass.html#another_method" translate="no">TestClass::another_method</a>().</p>
+<div class="admonition auto"><p>This function overloads <a href="testclass.html#another_method" translate="no">TestClass::another_method</a>().</p>
</div><!-- @@@another_method -->
<!-- $$$method[overload1]$$$method -->
<h3 class="fn" translate="no" id="method"><span class="type">void</span> TestClass::<span class="name">method</span>()</h3>