From a14d2e6fbf28881fabe691771ef049524dbef231 Mon Sep 17 00:00:00 2001 From: Gennaro Prota Date: Wed, 29 Apr 2026 10:37:50 +0200 Subject: [PATCH] fix: render inline markup correctly in Adoc and HTML Emphasis, subscript, and superscript in doc comments rendered incorrectly. Their common partials all delegated to the italic fallback `markup/i`. In AsciiDoc that yields italics: right for emphasis, wrong for subscript and superscript, which should be lowered and raised. In HTML `markup/i` has no counterpart, so emphasis collapsed to bare text; and the HTML inline dispatcher was a hardcoded list that omitted subscript and superscript, dropping them altogether. Doc comments may now also use the HTML-tag form for the inline-formatting kinds (``, ``, ``, ``, ``, ``), joining the previously-supported ``. This is what most users reach for when they need tight notation (e.g. `H2O`); the Markdown-marker forms require whitespace flanks, which makes compact chemistry and math notation awkward. Footnote-reference, image, and math share the same italic-fallback rendering but each needs its own design decision and is left for separate fixes. Closes issue #1185. --- docs/modules/ROOT/pages/commands/inlines.adoc | 2 + .../ROOT/partials/commands-registry.json | 14 +- .../DocComment/Inline/HighlightInline.hpp | 3 + .../DocComment/Inline/StrikethroughInline.hpp | 3 + .../DocComment/Inline/SubscriptInline.hpp | 3 + .../DocComment/Inline/SuperscriptInline.hpp | 3 + .../adoc/partials/markup/sub.adoc.hbs | 1 + .../adoc/partials/markup/sup.adoc.hbs | 1 + .../common/partials/doc/inline/emph.hbs | 2 +- .../common/partials/doc/inline/subscript.hbs | 2 +- .../partials/doc/inline/superscript.hbs | 2 +- .../html/partials/doc/inline.html.hbs | 7 - .../html/partials/markup/sub.html.hbs | 1 + .../html/partials/markup/sup.html.hbs | 1 + src/lib/AST/ExtractDocComment.cpp | 30 +++ .../javadoc/inline/inline-markers.adoc | 38 ++++ .../javadoc/inline/inline-markers.cpp | 15 ++ .../javadoc/inline/inline-markers.html | 48 +++++ .../javadoc/inline/inline-markers.xml | 181 ++++++++++++++++++ .../javadoc/inline/inline-markers.yml | 1 + .../snippets/commands/subscript.adoc | 2 +- .../snippets/commands/subscript.cpp | 2 +- .../snippets/commands/superscript.adoc | 2 +- .../snippets/commands/superscript.cpp | 2 +- 24 files changed, 346 insertions(+), 20 deletions(-) create mode 100644 share/mrdocs/addons/generator/adoc/partials/markup/sub.adoc.hbs create mode 100644 share/mrdocs/addons/generator/adoc/partials/markup/sup.adoc.hbs delete mode 100644 share/mrdocs/addons/generator/html/partials/doc/inline.html.hbs create mode 100644 share/mrdocs/addons/generator/html/partials/markup/sub.html.hbs create mode 100644 share/mrdocs/addons/generator/html/partials/markup/sup.html.hbs create mode 100644 test-files/golden-tests/javadoc/inline/inline-markers.adoc create mode 100644 test-files/golden-tests/javadoc/inline/inline-markers.cpp create mode 100644 test-files/golden-tests/javadoc/inline/inline-markers.html create mode 100644 test-files/golden-tests/javadoc/inline/inline-markers.xml create mode 100644 test-files/golden-tests/javadoc/inline/inline-markers.yml diff --git a/docs/modules/ROOT/pages/commands/inlines.adoc b/docs/modules/ROOT/pages/commands/inlines.adoc index 4b5b270d3d..e5712051ba 100644 --- a/docs/modules/ROOT/pages/commands/inlines.adoc +++ b/docs/modules/ROOT/pages/commands/inlines.adoc @@ -11,6 +11,8 @@ MrDocs reads the usual Markdown spans, with Doxygen and HTML equivalents alongsi * xref:commands/reference.adoc#cmd-code-span[Code span]: `+`text`+`. * xref:commands/reference.adoc#cmd-strikethrough[Strikethrough]: `+~~text~~+`. * xref:commands/reference.adoc#cmd-highlight[Highlight]: `+==text==+`. +* xref:commands/reference.adoc#cmd-subscript[Subscript]: `+~text~+` or `+text+`. +* xref:commands/reference.adoc#cmd-superscript[Superscript]: `+^text^+` or `+text+`. .Text formatting [source,cpp] diff --git a/docs/modules/ROOT/partials/commands-registry.json b/docs/modules/ROOT/partials/commands-registry.json index f6808f9274..5103b70886 100644 --- a/docs/modules/ROOT/partials/commands-registry.json +++ b/docs/modules/ROOT/partials/commands-registry.json @@ -681,7 +681,9 @@ "text" ], "partial": "commands/superscript.adoc", - "examples": [], + "examples": [ + "commands/superscript" + ], "see_also": [ "Subscript" ], @@ -692,8 +694,7 @@ "type": "Text", "description": "The text to raise as superscript." } - ], - "planned": true + ] }, { "node_type": "SubscriptInline", @@ -704,7 +705,9 @@ "text" ], "partial": "commands/subscript.adoc", - "examples": [], + "examples": [ + "commands/subscript" + ], "see_also": [ "Superscript" ], @@ -715,8 +718,7 @@ "type": "Text", "description": "The text to lower as subscript." } - ], - "planned": true + ] } ], "math": [ diff --git a/include/mrdocs/Metadata/DocComment/Inline/HighlightInline.hpp b/include/mrdocs/Metadata/DocComment/Inline/HighlightInline.hpp index 462aa5e7a0..85cdd51aa8 100644 --- a/include/mrdocs/Metadata/DocComment/Inline/HighlightInline.hpp +++ b/include/mrdocs/Metadata/DocComment/Inline/HighlightInline.hpp @@ -32,6 +32,9 @@ struct HighlightInline final : InlineCommonBase , InlineContainer { + /** Inherit text container constructors. + */ + using InlineContainer::InlineContainer; }; MRDOCS_DESCRIBE_STRUCT( diff --git a/include/mrdocs/Metadata/DocComment/Inline/StrikethroughInline.hpp b/include/mrdocs/Metadata/DocComment/Inline/StrikethroughInline.hpp index 1d6381d104..2f27963bd6 100644 --- a/include/mrdocs/Metadata/DocComment/Inline/StrikethroughInline.hpp +++ b/include/mrdocs/Metadata/DocComment/Inline/StrikethroughInline.hpp @@ -42,6 +42,9 @@ struct StrikethroughInline final : InlineCommonBase , InlineContainer { + /** Inherit text container constructors. + */ + using InlineContainer::InlineContainer; }; MRDOCS_DESCRIBE_STRUCT( diff --git a/include/mrdocs/Metadata/DocComment/Inline/SubscriptInline.hpp b/include/mrdocs/Metadata/DocComment/Inline/SubscriptInline.hpp index 3dda538ec8..6be59f3ecf 100644 --- a/include/mrdocs/Metadata/DocComment/Inline/SubscriptInline.hpp +++ b/include/mrdocs/Metadata/DocComment/Inline/SubscriptInline.hpp @@ -32,6 +32,9 @@ struct SubscriptInline final : InlineCommonBase , InlineContainer { + /** Inherit text container constructors. + */ + using InlineContainer::InlineContainer; }; MRDOCS_DESCRIBE_STRUCT( diff --git a/include/mrdocs/Metadata/DocComment/Inline/SuperscriptInline.hpp b/include/mrdocs/Metadata/DocComment/Inline/SuperscriptInline.hpp index eba06a32ad..3a9e32d28d 100644 --- a/include/mrdocs/Metadata/DocComment/Inline/SuperscriptInline.hpp +++ b/include/mrdocs/Metadata/DocComment/Inline/SuperscriptInline.hpp @@ -32,6 +32,9 @@ struct SuperscriptInline final : InlineCommonBase , InlineContainer { + /** Inherit text container constructors. + */ + using InlineContainer::InlineContainer; }; MRDOCS_DESCRIBE_STRUCT( diff --git a/share/mrdocs/addons/generator/adoc/partials/markup/sub.adoc.hbs b/share/mrdocs/addons/generator/adoc/partials/markup/sub.adoc.hbs new file mode 100644 index 0000000000..e988ee8ecb --- /dev/null +++ b/share/mrdocs/addons/generator/adoc/partials/markup/sub.adoc.hbs @@ -0,0 +1 @@ +~{{> @partial-block }}~ \ No newline at end of file diff --git a/share/mrdocs/addons/generator/adoc/partials/markup/sup.adoc.hbs b/share/mrdocs/addons/generator/adoc/partials/markup/sup.adoc.hbs new file mode 100644 index 0000000000..b49e3d0fbc --- /dev/null +++ b/share/mrdocs/addons/generator/adoc/partials/markup/sup.adoc.hbs @@ -0,0 +1 @@ +^{{> @partial-block }}^ \ No newline at end of file diff --git a/share/mrdocs/addons/generator/common/partials/doc/inline/emph.hbs b/share/mrdocs/addons/generator/common/partials/doc/inline/emph.hbs index 2bd7f82f10..5d98d43184 100644 --- a/share/mrdocs/addons/generator/common/partials/doc/inline/emph.hbs +++ b/share/mrdocs/addons/generator/common/partials/doc/inline/emph.hbs @@ -1 +1 @@ -{{#> markup/i }}{{> doc/inline-container }}{{/ markup/i }} \ No newline at end of file +{{#> markup/em }}{{> doc/inline-container }}{{/ markup/em }} \ No newline at end of file diff --git a/share/mrdocs/addons/generator/common/partials/doc/inline/subscript.hbs b/share/mrdocs/addons/generator/common/partials/doc/inline/subscript.hbs index 2bd7f82f10..0931070edf 100644 --- a/share/mrdocs/addons/generator/common/partials/doc/inline/subscript.hbs +++ b/share/mrdocs/addons/generator/common/partials/doc/inline/subscript.hbs @@ -1 +1 @@ -{{#> markup/i }}{{> doc/inline-container }}{{/ markup/i }} \ No newline at end of file +{{#> markup/sub }}{{> doc/inline-container }}{{/ markup/sub }} \ No newline at end of file diff --git a/share/mrdocs/addons/generator/common/partials/doc/inline/superscript.hbs b/share/mrdocs/addons/generator/common/partials/doc/inline/superscript.hbs index 2bd7f82f10..dde34cfc9b 100644 --- a/share/mrdocs/addons/generator/common/partials/doc/inline/superscript.hbs +++ b/share/mrdocs/addons/generator/common/partials/doc/inline/superscript.hbs @@ -1 +1 @@ -{{#> markup/i }}{{> doc/inline-container }}{{/ markup/i }} \ No newline at end of file +{{#> markup/sup }}{{> doc/inline-container }}{{/ markup/sup }} \ No newline at end of file diff --git a/share/mrdocs/addons/generator/html/partials/doc/inline.html.hbs b/share/mrdocs/addons/generator/html/partials/doc/inline.html.hbs deleted file mode 100644 index bd6c0e327d..0000000000 --- a/share/mrdocs/addons/generator/html/partials/doc/inline.html.hbs +++ /dev/null @@ -1,7 +0,0 @@ -{{~#if (eq kind "text")~}}{{> doc/inline/text}}{{~/if~}} -{{~#if (eq kind "strong")~}}{{> doc/inline/strong}}{{~/if~}} -{{~#if (eq kind "emph")~}}{{> doc/inline/emph}}{{~/if~}} -{{~#if (eq kind "code")~}}{{> doc/inline/code}}{{~/if~}} -{{~#if (eq kind "link")~}}{{> doc/inline/link}}{{~/if~}} -{{~#if (eq kind "reference")~}}{{> doc/inline/reference}}{{~/if~}} -{{~#if (eq kind "copy-details")~}}{{> doc/inline/copy-details}}{{~/if~}} \ No newline at end of file diff --git a/share/mrdocs/addons/generator/html/partials/markup/sub.html.hbs b/share/mrdocs/addons/generator/html/partials/markup/sub.html.hbs new file mode 100644 index 0000000000..a150818d88 --- /dev/null +++ b/share/mrdocs/addons/generator/html/partials/markup/sub.html.hbs @@ -0,0 +1 @@ +{{> @partial-block }} \ No newline at end of file diff --git a/share/mrdocs/addons/generator/html/partials/markup/sup.html.hbs b/share/mrdocs/addons/generator/html/partials/markup/sup.html.hbs new file mode 100644 index 0000000000..cdf1daa31b --- /dev/null +++ b/share/mrdocs/addons/generator/html/partials/markup/sup.html.hbs @@ -0,0 +1 @@ +{{> @partial-block }} \ No newline at end of file diff --git a/src/lib/AST/ExtractDocComment.cpp b/src/lib/AST/ExtractDocComment.cpp index 8e1646bcfc..1cfd985a70 100644 --- a/src/lib/AST/ExtractDocComment.cpp +++ b/src/lib/AST/ExtractDocComment.cpp @@ -1119,6 +1119,36 @@ class DocCommentVisitor C->hasTrailingNewline(), ensureUTF8(std::move(comps.text))); } + else if (comps.tag == "strong") + { + emplaceInline( + C->hasTrailingNewline(), + ensureUTF8(std::move(comps.text))); + } + else if (comps.tag == "mark") + { + emplaceInline( + C->hasTrailingNewline(), + ensureUTF8(std::move(comps.text))); + } + else if (comps.tag == "sub") + { + emplaceInline( + C->hasTrailingNewline(), + ensureUTF8(std::move(comps.text))); + } + else if (comps.tag == "sup") + { + emplaceInline( + C->hasTrailingNewline(), + ensureUTF8(std::move(comps.text))); + } + else if (comps.tag == "del" || comps.tag == "s") + { + emplaceInline( + C->hasTrailingNewline(), + ensureUTF8(std::move(comps.text))); + } else { report::warn( diff --git a/test-files/golden-tests/javadoc/inline/inline-markers.adoc b/test-files/golden-tests/javadoc/inline/inline-markers.adoc new file mode 100644 index 0000000000..e55ce95b33 --- /dev/null +++ b/test-files/golden-tests/javadoc/inline/inline-markers.adoc @@ -0,0 +1,38 @@ += Reference +:mrdocs: + +[#index] +== Global namespace + +=== Functions + +[cols="1,4"] +|=== +| Name| Description +| link:#f[`f`] +| Exercise the inline markup kinds (HTML and Markdown forms): subscript, superscript, highlight, strikethrough. +|=== + +[#f] +== f + +Exercise the inline markup kinds (HTML and Markdown forms): subscript, superscript, highlight, strikethrough. + +=== Synopsis + +Declared in `<inline‐markers.cpp>` + +[source,cpp,subs="verbatim,replacements,macros,-callouts"] +---- +void +f(); +---- + +=== Description + +HTML form (works in tight notation): H~2~O is water; x^2^ is x squared. *Bold*, #highlighted#, [.line-through]#struck‐through#, and [.line-through]#also struck# text. + +Markdown form (requires whitespace flanks): Subscript: ~i~ indicates an index. Superscript: raise to the ^n^ power. Strong: *bold*. Highlight: #highlighted#. Strikethrough: [.line-through]#struck‐through#. + + +[.small]#Created with https://www.mrdocs.com[MrDocs]# diff --git a/test-files/golden-tests/javadoc/inline/inline-markers.cpp b/test-files/golden-tests/javadoc/inline/inline-markers.cpp new file mode 100644 index 0000000000..dd4f729e74 --- /dev/null +++ b/test-files/golden-tests/javadoc/inline/inline-markers.cpp @@ -0,0 +1,15 @@ +/** Exercise the inline markup kinds (HTML and Markdown forms): + subscript, superscript, highlight, strikethrough. + + HTML form (works in tight notation): + H2O is water; x2 is x squared. + Bold, highlighted, + struck-through, and also struck text. + + Markdown form (requires whitespace flanks): + Subscript: ~i~ indicates an index. Superscript: raise to the + ^n^ power. + Strong: **bold**. Highlight: ==highlighted==. + Strikethrough: ~~struck-through~~. + */ +void f(); diff --git a/test-files/golden-tests/javadoc/inline/inline-markers.html b/test-files/golden-tests/javadoc/inline/inline-markers.html new file mode 100644 index 0000000000..23f04d7c4c --- /dev/null +++ b/test-files/golden-tests/javadoc/inline/inline-markers.html @@ -0,0 +1,48 @@ + + +Reference + + + +
+

Reference

+
+
+

Global namespace

+
+

Functions

+ + + + + + + +
NameDescription
f Exercise the inline markup kinds (HTML and Markdown forms): subscript, superscript, highlight, strikethrough.
+ +
+
+
+

f

+
+

Exercise the inline markup kinds (HTML and Markdown forms): subscript, superscript, highlight, strikethrough.

+
+
+

Synopsis

+

Declared in <inline-markers.cpp>

+
void
+f();
+
+
+

Description

+

HTML form (works in tight notation): H2O is water; x2 is x squared. Bold, highlighted, struck-through, and also struck text.

+

Markdown form (requires whitespace flanks): Subscript: i indicates an index. Superscript: raise to the n power. Strong: bold. Highlight: highlighted. Strikethrough: struck-through.

+
+
+ +
+ + + \ No newline at end of file diff --git a/test-files/golden-tests/javadoc/inline/inline-markers.xml b/test-files/golden-tests/javadoc/inline/inline-markers.xml new file mode 100644 index 0000000000..850ccde381 --- /dev/null +++ b/test-files/golden-tests/javadoc/inline/inline-markers.xml @@ -0,0 +1,181 @@ + + + + + + namespace + //////////////////////////8= + regular + + s6nsa+zVhpzzrN+yUVPP5rvdXqs= + + + + f + + + inline-markers.cpp + inline-markers.cpp + 15 + 1 + 1 + + + function + s6nsa+zVhpzzrN+yUVPP5rvdXqs= + regular + //////////////////////////8= + + + paragraph + + text + HTML form (works in tight notation): H + + + subscript + + text + 2 + + + + text + O is water; x + + + superscript + + text + 2 + + + + text + is x squared. + + + strong + + text + Bold + + + + text + , + + + highlight + + text + highlighted + + + + text + , + + + strikethrough + + text + struck-through + + + + text + , and + + + strikethrough + + text + also struck + + + + text + text. + + + + paragraph + + text + Markdown form (requires whitespace flanks): Subscript: + + + subscript + + text + i + + + + text + indicates an index. Superscript: raise to the + + + superscript + + text + n + + + + text + power. Strong: + + + strong + + text + bold + + + + text + . Highlight: + + + highlight + + text + highlighted + + + + text + . Strikethrough: + + + strikethrough + + text + struck-through + + + + text + . + + + + brief + + text + Exercise the inline markup kinds (HTML and Markdown forms): subscript, superscript, highlight, strikethrough. + + + + + + identifier + void + + + normal + + diff --git a/test-files/golden-tests/javadoc/inline/inline-markers.yml b/test-files/golden-tests/javadoc/inline/inline-markers.yml new file mode 100644 index 0000000000..0adfa7977d --- /dev/null +++ b/test-files/golden-tests/javadoc/inline/inline-markers.yml @@ -0,0 +1 @@ +generator: [xml, adoc, html] diff --git a/test-files/golden-tests/snippets/commands/subscript.adoc b/test-files/golden-tests/snippets/commands/subscript.adoc index 2b5028feb7..56d27d70e7 100644 --- a/test-files/golden-tests/snippets/commands/subscript.adoc +++ b/test-files/golden-tests/snippets/commands/subscript.adoc @@ -4,7 +4,7 @@ [#coefficient] == coefficient -Reads coefficient a~i~ from the polynomial. +Reads coefficient a~i~ from the polynomial. === Synopsis diff --git a/test-files/golden-tests/snippets/commands/subscript.cpp b/test-files/golden-tests/snippets/commands/subscript.cpp index 4c51fcab01..c71cab209c 100644 --- a/test-files/golden-tests/snippets/commands/subscript.cpp +++ b/test-files/golden-tests/snippets/commands/subscript.cpp @@ -1,3 +1,3 @@ -/** Reads coefficient a~i~ from the polynomial. +/** Reads coefficient ai from the polynomial. */ double coefficient(unsigned i); diff --git a/test-files/golden-tests/snippets/commands/superscript.adoc b/test-files/golden-tests/snippets/commands/superscript.adoc index 95d20422f5..242ae354a7 100644 --- a/test-files/golden-tests/snippets/commands/superscript.adoc +++ b/test-files/golden-tests/snippets/commands/superscript.adoc @@ -4,7 +4,7 @@ [#power_of_two] == power_of_two -Computes 2ˆnˆ in constant time. +Computes 2^n^ in constant time. === Synopsis diff --git a/test-files/golden-tests/snippets/commands/superscript.cpp b/test-files/golden-tests/snippets/commands/superscript.cpp index 83907e7be0..bc38ec6ec8 100644 --- a/test-files/golden-tests/snippets/commands/superscript.cpp +++ b/test-files/golden-tests/snippets/commands/superscript.cpp @@ -1,4 +1,4 @@ -/** Computes 2^n^ in constant time. +/** Computes 2n in constant time. Returns 1 when `n` is zero. */