diff options
author | Paul Wicking <paul.wicking@qt.io> | 2025-05-08 10:12:03 +0200 |
---|---|---|
committer | Paul Wicking <paul.wicking@qt.io> | 2025-05-09 11:12:04 +0200 |
commit | fd37afd39f6a589f90e827b585b13a0afb5196d2 (patch) | |
tree | 54efd1912a54a0d89f32378b9d2725dc2f9e5225 | |
parent | f3ef3cff765082f439cd1a7bfb8822beaa28784a (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.cpp | 26 | ||||
-rw-r--r-- | src/qdoc/qdoc/src/qdoc/docbookgenerator.h | 2 | ||||
-rw-r--r-- | src/qdoc/qdoc/src/qdoc/generator.cpp | 17 | ||||
-rw-r--r-- | src/qdoc/qdoc/src/qdoc/generator.h | 10 | ||||
-rw-r--r-- | src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/overload_command/expected/testclass.html | 4 |
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 §ion, 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> |