cppalliance · alandefreitas · Mar 12, 2025 · Mar 12, 2025
diff --git a/include/mrdocs/Metadata/Javadoc.hpp b/include/mrdocs/Metadata/Javadoc.hpp
@@ -1205,70 +1205,14 @@ tag_invoke(
     v = dom::LazyObject(I, domCorpus);
 }
 
-/** A @details paragraph
-*/
-struct Details final : Paragraph
-{
-    static constexpr auto static_kind = NodeKind::details;
-
-    Details()
-        : Paragraph(NodeKind::details)
-    {}
-
-    auto operator<=>(Details const&) const = default;
-
-    bool
-    operator==(Details const&) const noexcept = default;
-
-    bool equals(Node const& other) const noexcept override
-    {
-        auto* p = dynamic_cast<Details const*>(&other);
-        if (!p)
-        {
-            return false;
-        }
-        if (this == &other)
-        {
-            return true;
-        }
-        return *this == *p;
-    }
-};
-
-/** Map the @ref Details to a @ref dom::Object.
- */
-template <class IO>
-void
-tag_invoke(
-    dom::LazyObjectMapTag t,
-    IO& io,
-    Details const& I,
-    DomCorpus const* domCorpus)
-{
-    tag_invoke(t, io, dynamic_cast<Paragraph const&>(I), domCorpus);
-}
-
-/** Return the @ref Details as a @ref dom::Value object.
- */
-inline
-void
-tag_invoke(
-    dom::ValueFromTag,
-    dom::Value& v,
-    Details const& I,
-    DomCorpus const* domCorpus)
-{
-    v = dom::LazyObject(I, domCorpus);
-}
-
 /** A @see paragraph
 */
 struct See final : Paragraph
 {
     static constexpr auto static_kind = NodeKind::see;
 
     See()
-        : Paragraph(NodeKind::see)
+        : Paragraph(static_kind)
     {
     }
 
@@ -1682,8 +1626,6 @@ visit(
         return visitor.template visit<TParam>();
     case NodeKind::throws:
         return visitor.template visit<Throws>();
-    case NodeKind::details:
-        return visitor.template visit<Details>();
     case NodeKind::see:
         return visitor.template visit<See>();
     case NodeKind::precondition:
@@ -1901,7 +1843,7 @@ tag_invoke(
     Javadoc const& I,
     DomCorpus const* domCorpus)
 {
-    io.defer("details", [&I, domCorpus] {
+    io.defer("description", [&I, domCorpus] {
         return dom::LazyArray(I.blocks, domCorpus);
     });
     if (I.brief)

diff --git a/share/mrdocs/addons/generator/adoc/layouts/wrapper.adoc.hbs b/share/mrdocs/addons/generator/adoc/layouts/wrapper.adoc.hbs
@@ -1,47 +1,27 @@
-{{! The wrapper for single page documentation or symbols in a multipage documentation }}
-{{! Title }}
-{{#if @root.config.multipage }}
-{{! Multipage documentation: symbol is available to the wrapper }}
-[#{{{symbol.anchor}}}]
-{{!
-    This title qualified name does not include links as the Antora
-    UI is not able to render these links in the title.
-
-    Breadcrumbs are included in the symbol template as an alternative.
-}}
-= {{> symbol/qualified-name symbol }}
-{{!
-    Antora does not support relative links to pages in
-    parent directories. Therefore, unlike in HTML templates,
-    links are not relativized.
-
-    However, while Antora interprets xref as relative
-    to the root of the module, these xref are
-    interpreted as relative to the current directory
-    because it has no concept of modules. This means
-    links would be broken with either Antora or Asciidoc.
+{{!--
+    Wraps the documentation for a symbol (multipage) or all symbols (single page).
 
-    Even more, Antora uses the same rule as Asciidoc
-    for breadcrumbs and the page title, where links
-    would also be broken.
+    The {{{contents}}} tag can be used to include the content of the symbol or symbols
+    to be wrapped by this template.
 
-    The solution is to set the relfileprefix attribute,
-    which includes the relative location of the root
-    directory and makes all links relative to it.
+    The multipage mode, the wrapper also receives the symbol object to render the title
+    and the breadcrumbs.
 
-    This relfileprefix affects Asciidoc links, the
-    Antora title, and the Antora breadcrumbs.
+    In the single page mode, the symbol object is not available to the wrapper, but it
+    is available to the symbol template. In this case, the title is simply "Reference".
 
-    See https://docs.asciidoctor.org/asciidoc/latest/macros/inter-document-xref/#mapping-references-to-a-different-structure
-}}
+    As Antora does not support relative links to pages in parent directories, the
+    relfileprefix attribute is set to make all links relative to the root directory.
+    This is only necessary in multipage mode.
+--}}
+{{#if @root.config.multipage }}
+[#{{{symbol.anchor}}}]
+= {{> symbol/qualified-name symbol }}
 :relfileprefix: {{{ repeat "../" (count (remove_prefix symbol.url '/') '/') }}}
 {{else}}
-{{! Single page documentation: symbol is not available to the wrapper }}
 = Reference
 {{/if}}
 :mrdocs:
 
-{{! Content generated with index.hbs }}
 {{{contents}}}
-
-[.small]#Created with https://www.mrdocs.com[MrDocs]#
+{{#>markup/span class="small"}}Created with https://www.mrdocs.com[MrDocs]{{/markup/span}}
diff --git a/share/mrdocs/addons/generator/adoc/partials/javadoc/brief.adoc.hbs b/share/mrdocs/addons/generator/adoc/partials/javadoc/brief.adoc.hbs
@@ -0,0 +1,3 @@
+{{>javadoc/inline-brief}}
+
+
diff --git a/share/mrdocs/addons/generator/adoc/partials/javadoc/description.adoc.hbs b/share/mrdocs/addons/generator/adoc/partials/javadoc/description.adoc.hbs
@@ -0,0 +1 @@
+{{#each .}}{{>javadoc/any-block .}}{{/each}}
diff --git a/share/mrdocs/addons/generator/adoc/partials/javadoc/detail-blocks.adoc.hbs b/share/mrdocs/addons/generator/adoc/partials/javadoc/detail-blocks.adoc.hbs
diff --git a/share/mrdocs/addons/generator/adoc/partials/javadoc/heading.adoc.hbs b/share/mrdocs/addons/generator/adoc/partials/javadoc/heading.adoc.hbs
@@ -1,3 +1 @@
-
-=== {{string}}
-
+{{#> markup/dynamic-level-h level=1 }}{{string}}{{/markup/dynamic-level-h}}
diff --git a/share/mrdocs/addons/generator/adoc/partials/markup/h.adoc.hbs b/share/mrdocs/addons/generator/adoc/partials/markup/h.adoc.hbs
@@ -1,3 +1,19 @@
+{{!--
+    Renders a heading element with an optional ID attribute.
+
+    This partial generates a heading element (`h1`, `h2`, etc.) based on the provided level.
+    If an ID is provided, it will be included as an anchor for the heading.
+
+    Parameters:
+        - partial block: The content to be rendered inside the heading element.
+        - level: The level of the heading element (1, 2, etc.).
+        - id: An optional ID attribute for the heading element.
+
+    Example:
+        {{> markup/h level=2 id="section-id" }}Section Title{{/markup/h}}
+
+    See: https://mrdocs.com/docs/mrdocs/develop/generators.html#dom_reference
+--}}
 {{#if id}}[#{{{id}}}]
 {{/if}}
 ={{{select level (repeat "=" level) (select @root.config.multipage "==" "=")}}} {{> @partial-block }}
diff --git a/share/mrdocs/addons/generator/adoc/partials/markup/th.adoc.hbs b/share/mrdocs/addons/generator/adoc/partials/markup/th.adoc.hbs
@@ -1 +1 @@
-| {{> @partial-block }} 
+| {{> @partial-block }}
diff --git a/share/mrdocs/addons/generator/adoc/partials/markup/thead.adoc.hbs b/share/mrdocs/addons/generator/adoc/partials/markup/thead.adoc.hbs
@@ -1,2 +1 @@
-{{> @partial-block }}
-
+{{> @partial-block }}
diff --git a/share/mrdocs/addons/generator/adoc/partials/markup/tr.adoc.hbs b/share/mrdocs/addons/generator/adoc/partials/markup/tr.adoc.hbs
@@ -1 +1 @@
-{{> @partial-block }}
+{{> @partial-block }}
diff --git a/share/mrdocs/addons/generator/adoc/partials/symbol.adoc.hbs b/share/mrdocs/addons/generator/adoc/partials/symbol.adoc.hbs
@@ -16,17 +16,13 @@
 {{! Include the symbol title at a higher level }}
 {{#> markup/h level=1 id=symbol.anchor }}{{> symbol/qualified-name symbol }}{{/markup/h}}
 {{/unless}}
-
 {{! Brief }}
 {{#if symbol.doc.brief}}
 {{> javadoc/brief symbol.doc.brief }}
-
-
 {{/if}}
 {{! Synopsis }}
 {{#unless (eq symbol.kind "namespace")}}
 {{#> markup/dynamic-level-h }}{{#if (ne symbol.kind "overloads")}}Synopsis{{else}}Synopses{{/if}}{{/markup/dynamic-level-h}}
-
 {{>location/source dcl=(primary_location symbol)}}
 
 
@@ -37,16 +33,12 @@
 {{#if (eq symbol.kind "record")}}
 {{#with symbol.interface}}
 {{>symbol/tranche tranche=public label="" is-namespace=false}}
-
 {{>symbol/tranche tranche=protected label="Protected" is-namespace=false}}
-
 {{>symbol/tranche tranche=private label="Private" is-namespace=false}}
-
 {{/with}}
 {{! Namespace members }}
 {{else if (eq symbol.kind "namespace")}}
 {{>symbol/tranche tranche=symbol.members label="" is-namespace=true}}
-
 {{! Enum members }}
 {{else if (eq symbol.kind "enum")}}
 {{#if symbol.constants}}
@@ -61,7 +53,7 @@
 {{else}}
 |`{{>symbol/name . nolink=true}}`
 {{/if}}
-|{{> javadoc/brief doc.brief }}
+|{{> javadoc/inline-brief doc.brief }}
 {{/each}}
 |===
 
@@ -78,10 +70,9 @@
 
 {{/if}}
 {{! Description }}
-{{#if symbol.doc.details}}
+{{#if symbol.doc.description}}
 {{#> markup/dynamic-level-h }}Description{{/markup/dynamic-level-h}}
-
-{{> javadoc/detail-blocks symbol.doc.details }}
+{{> javadoc/description symbol.doc.description }}
 {{/if}}
 {{! Using symbols }}
 {{#if symbol.shadows}}
@@ -98,94 +89,74 @@
 {{! Exceptions }}
 {{#if symbol.doc.exceptions}}
 {{#> markup/dynamic-level-h }}Exceptions{{/markup/dynamic-level-h}}
-
 |===
-| Name | Thrown on
-
+| Name
+| Thrown on
 {{#each symbol.doc.exceptions}}
 | {{> javadoc/reference exception}}
 | {{>javadoc/block .}}
-
 {{/each}}
 |===
 
 {{/if}}
 {{! Return value }}
 {{#if symbol.doc.returns}}
 {{#> markup/dynamic-level-h }}Return Value{{/markup/dynamic-level-h}}
-
 {{#if (eq (size symbol.doc.returns) 1)}}
 {{> javadoc/returns symbol.doc.returns.[0]}}
 
+
 {{else}}
 {{#each symbol.doc.returns}}
 * {{> javadoc/returns .}}
 {{/each}}
-{{/if}}
 
+{{/if}}
 {{/if}}
 {{! Template Parameters }}
 {{#if symbol.doc.tparams}}
 {{#> markup/dynamic-level-h }}Template Parameters{{/markup/dynamic-level-h}}
-
 |===
-| Name | Description
-
+| Name
+| Description
 {{#each symbol.doc.tparams}}
 | *{{name}}*
 | {{>javadoc/block .}}
-
 {{/each}}
 |===
 
 {{/if}}
 {{! Parameters }}
 {{#if symbol.doc.params}}
 {{#> markup/dynamic-level-h }}Parameters{{/markup/dynamic-level-h}}
-
 |===
-| Name | Description
-
+| Name
+| Description
 {{#each symbol.doc.params}}
 | *{{name}}*{{#if direction}} [{{direction}}]{{/if}}
 | {{>javadoc/block .}}
-
 {{/each}}
 |===
 
 {{/if}}
 {{! Preconditions }}
 {{#if symbol.doc.preconditions}}
 {{#> markup/dynamic-level-h }}Preconditions{{/markup/dynamic-level-h}}
-
-{{#each symbol.doc.preconditions}}
-* {{>javadoc/block .}}
+{{#each symbol.doc.preconditions}}* {{>javadoc/block .}}
 {{/each}}
 
-
-
 {{/if}}
 {{! Postconditions }}
 {{#if symbol.doc.postconditions}}
 {{#> markup/dynamic-level-h }}Postconditions{{/markup/dynamic-level-h}}
-
-{{#each symbol.doc.postconditions}}
-* {{>javadoc/block .}}
+{{#each symbol.doc.postconditions}}* {{>javadoc/block .}}
 {{/each}}
 
-
-
 {{/if}}
 {{! See Also }}
 {{#if symbol.doc.sees}}
 {{#> markup/dynamic-level-h }}See Also{{/markup/dynamic-level-h}}
-
 {{#each symbol.doc.sees}}
-{{>javadoc/block .}}
-
+{{>javadoc/see .}}
 {{/each}}
-
-
-
-
-{{/if}}
+{{/if}}
diff --git a/share/mrdocs/addons/generator/common/partials/javadoc/inline-brief.hbs b/share/mrdocs/addons/generator/common/partials/javadoc/inline-brief.hbs
@@ -0,0 +1 @@
+{{>javadoc/block}}
diff --git a/...rator/common/partials/javadoc/details.hbs → ...generator/common/partials/javadoc/see.hbs b/...rator/common/partials/javadoc/details.hbs → ...generator/common/partials/javadoc/see.hbs
diff --git a/share/mrdocs/addons/generator/common/partials/markup/dynamic-level-h.hbs b/share/mrdocs/addons/generator/common/partials/markup/dynamic-level-h.hbs
@@ -1,3 +1,23 @@
+{{!--
+    Renders a heading element with a dynamic level and an optional ID attribute.
+
+    This partial generates a heading element (`h1`, `h2`, etc.) based on the provided level.
+    The level is determined by the `multipage` configuration option, where
+    the level is incremented by 1 if the `multipage` option is disabled
+    because in single page documentation, the symbol title is rendered at level 2.
+
+    If an ID is provided, it will be included as an anchor for the heading.
+
+    Parameters:
+        - partial block: The content to be rendered inside the heading element.
+        - level: The level of the heading element (1, 2, etc.).
+        - id: An optional ID attribute for the heading element.
+
+    Example:
+        {{> markup/dynamic-level-h level=2 id="section-id" }}Section Title{{/markup/h}}
+
+    See: https://mrdocs.com/docs/mrdocs/develop/generators.html#dom_reference
+--}}
 {{#> markup/h
     level=(select @root.config.multipage (or level 1) (add (or level 1) 1))
     id=id
Original file line number	Diff line number	Diff line change
		@@ -1,3 +1 @@

		=== {{string}}

		{{#> markup/dynamic-level-h level=1 }}{{string}}{{/markup/dynamic-level-h}}