From 35d81dc7b08102acbd5e6685b86622bcaf10f897 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 HTML and Adoc Five kinds of inline markup in doc comments (emphasis, highlight, subscript, superscript, and strikethrough) were not rendered correctly: - HTML output silently dropped the wrapping element, so emphasized text and the others appeared as bare text. - AsciiDoc output rendered all five as italics, which is correct for emphasis but semantically wrong for the others (e.g., a subscript appeared as italic text, not lowered). Both rendering paths now produce semantically appropriate markup: ``, ``, ``, ``, `` in HTML, and the matching constructs in AsciiDoc (with strikethrough using the role-based `[.line-through]#...#`, since AsciiDoc has no native syntax for it). Doc comments may now also use the HTML-tag form for these kinds (``, ``, ``, ``, ``, ``) alongside the previously-supported ``. This is what most users reach for when they need a tight notation (e.g., `H2O`); the Markdown-marker forms (`~text~`, `^text^`, `==text==`, `~~text~~`) require whitespace flanks, which makes compact chemistry/math notation awkward to express. Three other inline kinds (footnote-reference, image, and math) suffer from the same rendering issue but each requires its own non-trivial design decision and is left for separate fixes. Closes issue #1185. --- .../DocComment/Inline/HighlightInline.hpp | 3 + .../DocComment/Inline/StrikethroughInline.hpp | 3 + .../DocComment/Inline/SubscriptInline.hpp | 3 + .../DocComment/Inline/SuperscriptInline.hpp | 3 + .../adoc/partials/markup/del.adoc.hbs | 1 + .../adoc/partials/markup/mark.adoc.hbs | 1 + .../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/highlight.hbs | 2 +- .../partials/doc/inline/strikethrough.hbs | 2 +- .../common/partials/doc/inline/subscript.hbs | 2 +- .../partials/doc/inline/superscript.hbs | 2 +- .../html/partials/doc/inline.html.hbs | 6 +- .../html/partials/markup/del.html.hbs | 1 + .../html/partials/markup/mark.html.hbs | 1 + .../html/partials/markup/sub.html.hbs | 1 + .../html/partials/markup/sup.html.hbs | 1 + src/lib/AST/ExtractDocComment.cpp | 30 +++ .../javadoc/html-table/inline.html | 4 +- .../javadoc/inline/inline-markers.adoc | 38 ++++ .../javadoc/inline/inline-markers.cpp | 15 ++ .../javadoc/inline/inline-markers.html | 58 ++++++ .../javadoc/inline/inline-markers.xml | 181 ++++++++++++++++++ .../golden-tests/javadoc/inline/styled.html | 2 +- 25 files changed, 355 insertions(+), 9 deletions(-) create mode 100644 share/mrdocs/addons/generator/adoc/partials/markup/del.adoc.hbs create mode 100644 share/mrdocs/addons/generator/adoc/partials/markup/mark.adoc.hbs 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 create mode 100644 share/mrdocs/addons/generator/html/partials/markup/del.html.hbs create mode 100644 share/mrdocs/addons/generator/html/partials/markup/mark.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 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/del.adoc.hbs b/share/mrdocs/addons/generator/adoc/partials/markup/del.adoc.hbs new file mode 100644 index 0000000000..6aaf2256a3 --- /dev/null +++ b/share/mrdocs/addons/generator/adoc/partials/markup/del.adoc.hbs @@ -0,0 +1 @@ +[.line-through]#{{> @partial-block }}# \ No newline at end of file diff --git a/share/mrdocs/addons/generator/adoc/partials/markup/mark.adoc.hbs b/share/mrdocs/addons/generator/adoc/partials/markup/mark.adoc.hbs new file mode 100644 index 0000000000..59a3111633 --- /dev/null +++ b/share/mrdocs/addons/generator/adoc/partials/markup/mark.adoc.hbs @@ -0,0 +1 @@ +#{{> @partial-block }}# \ No newline at end of file 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/highlight.hbs b/share/mrdocs/addons/generator/common/partials/doc/inline/highlight.hbs index 2bd7f82f10..4823daa012 100644 --- a/share/mrdocs/addons/generator/common/partials/doc/inline/highlight.hbs +++ b/share/mrdocs/addons/generator/common/partials/doc/inline/highlight.hbs @@ -1 +1 @@ -{{#> markup/i }}{{> doc/inline-container }}{{/ markup/i }} \ No newline at end of file +{{#> markup/mark }}{{> doc/inline-container }}{{/ markup/mark }} \ No newline at end of file diff --git a/share/mrdocs/addons/generator/common/partials/doc/inline/strikethrough.hbs b/share/mrdocs/addons/generator/common/partials/doc/inline/strikethrough.hbs index 2bd7f82f10..0880f93106 100644 --- a/share/mrdocs/addons/generator/common/partials/doc/inline/strikethrough.hbs +++ b/share/mrdocs/addons/generator/common/partials/doc/inline/strikethrough.hbs @@ -1 +1 @@ -{{#> markup/i }}{{> doc/inline-container }}{{/ markup/i }} \ No newline at end of file +{{#> markup/del }}{{> doc/inline-container }}{{/ markup/del }} \ 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 index bd6c0e327d..a6ff3a3918 100644 --- a/share/mrdocs/addons/generator/html/partials/doc/inline.html.hbs +++ b/share/mrdocs/addons/generator/html/partials/doc/inline.html.hbs @@ -4,4 +4,8 @@ {{~#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 +{{~#if (eq kind "copy-details")~}}{{> doc/inline/copy-details}}{{~/if~}} +{{~#if (eq kind "highlight")~}}{{> doc/inline/highlight}}{{~/if~}} +{{~#if (eq kind "strikethrough")~}}{{> doc/inline/strikethrough}}{{~/if~}} +{{~#if (eq kind "subscript")~}}{{> doc/inline/subscript}}{{~/if~}} +{{~#if (eq kind "superscript")~}}{{> doc/inline/superscript}}{{~/if~}} \ No newline at end of file diff --git a/share/mrdocs/addons/generator/html/partials/markup/del.html.hbs b/share/mrdocs/addons/generator/html/partials/markup/del.html.hbs new file mode 100644 index 0000000000..72b4eab449 --- /dev/null +++ b/share/mrdocs/addons/generator/html/partials/markup/del.html.hbs @@ -0,0 +1 @@ +{{> @partial-block }} \ No newline at end of file diff --git a/share/mrdocs/addons/generator/html/partials/markup/mark.html.hbs b/share/mrdocs/addons/generator/html/partials/markup/mark.html.hbs new file mode 100644 index 0000000000..18f5a8e3fc --- /dev/null +++ b/share/mrdocs/addons/generator/html/partials/markup/mark.html.hbs @@ -0,0 +1 @@ +{{> @partial-block }} \ 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 72961c8927..4ac0dba3b6 100644 --- a/src/lib/AST/ExtractDocComment.cpp +++ b/src/lib/AST/ExtractDocComment.cpp @@ -1089,6 +1089,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/html-table/inline.html b/test-files/golden-tests/javadoc/html-table/inline.html index 8ebef9e8f3..fc098be0dd 100644 --- a/test-files/golden-tests/javadoc/html-table/inline.html +++ b/test-files/golden-tests/javadoc/html-table/inline.html @@ -55,12 +55,12 @@

Reference -fixed +fixed 23.50 cppreference -scientific +scientific 2.35e+01 cppreference 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..63b1203b64 --- /dev/null +++ b/test-files/golden-tests/javadoc/inline/inline-markers.html @@ -0,0 +1,58 @@ + + +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/styled.html b/test-files/golden-tests/javadoc/inline/styled.html index 0a81200c8a..c20ae75bea 100644 --- a/test-files/golden-tests/javadoc/inline/styled.html +++ b/test-files/golden-tests/javadoc/inline/styled.html @@ -44,7 +44,7 @@

Description

-

Paragraph with code, bold text, and italic text.

+

Paragraph with code, bold text, and italic text.

We can also escape these markers: `, *, and _.