feat: render dependent noexcept specifications as noexcept(see-below)

MrDocs used to render the full `noexcept` operand inline, so a
declaration like

    void swap(reference, reference) noexcept(
      std::is_nothrow_move_constructible<value_t>::value &&
      std::is_nothrow_move_assignable<value_t>::value &&
      std::is_nothrow_move_constructible<json_value>::value &&
      std::is_nothrow_move_assignable<json_value>::value);

buried the `noexcept` condition in a mostly-unreadable slop.

This replaces dependent operands with an italic "see-below" placeholder
in the declaration, and moves the actual condition to a dedicated
"noexcept Specification" section of the exposition:

    void swap(reference, reference) noexcept(see-below);

    === noexcept Specification
    noexcept when `...long condition...`.

The section is intentionally separate from the existing "Exceptions"
section, which continues to cover `@throws` documentation.

Closes issue #1103.

Author: gennaroprota

include/mrdocs/Metadata/Specifiers/ExplicitInfo.hpp

@@ -14,6 +14,7 @@
 
 #include <mrdocs/Platform.hpp>
 #include <mrdocs/Metadata/Specifiers/ExplicitKind.hpp>
+#include <mrdocs/Support/Describe.hpp>
 #include <string>
 
 namespace mrdocs {
@@ -27,7 +28,7 @@ struct ExplicitInfo
 {
     /** Whether an explicit-specifier was user-written.
     */
-    bool Implicit = true;
+    bool IsUserWritten = false;
 
     /** The evaluated exception specification.
     */
@@ -42,6 +43,11 @@ struct ExplicitInfo
     auto operator<=>(ExplicitInfo const&) const = default;
 };
 
+MRDOCS_DESCRIBE_STRUCT(
+    ExplicitInfo,
+    (),
+    (IsUserWritten, Kind, Operand))
+
 /** Convert ExplicitInfo to a string.
 
     @param info The explicit-specifier information.
@@ -57,21 +63,6 @@ toString(
     bool resolved = false,
     bool implicit = false);
 
-/** Return the ExplicitInfo as a @ref dom::Value string.
-
-    @param v The output parameter to receive the dom::Value.
-    @param I The ExplicitInfo to convert.
-*/
-inline
-void
-tag_invoke(
-    dom::ValueFromTag,
-    dom::Value& v,
-    ExplicitInfo const& I)
-{
-    v = toString(I);
-}
-
 } // mrdocs
 
 #endif

include/mrdocs/Metadata/Specifiers/ExplicitKind.hpp

@@ -13,8 +13,7 @@
 #define MRDOCS_API_METADATA_SPECIFIERS_EXPLICITKIND_HPP
 
 #include <mrdocs/Platform.hpp>
-#include <mrdocs/Dom/String.hpp>
-#include <string>
+#include <mrdocs/Support/Describe.hpp>
 
 namespace mrdocs {
 
@@ -33,11 +32,7 @@ enum class ExplicitKind
     Dependent
 };
 
-/** Convert an explicit kind to its string form.
-*/
-MRDOCS_DECL
-dom::String
-toString(ExplicitKind kind) noexcept;
+MRDOCS_DESCRIBE_ENUM(ExplicitKind, False, True, Dependent)
 
 } // mrdocs
 

include/mrdocs/Metadata/Specifiers/NoexceptInfo.hpp

@@ -18,6 +18,7 @@
 #include <mrdocs/Metadata/Specifiers/ExplicitInfo.hpp>
 #include <mrdocs/Metadata/Specifiers/ExplicitKind.hpp>
 #include <mrdocs/Metadata/Specifiers/NoexceptKind.hpp>
+#include <mrdocs/Support/Describe.hpp>
 #include <string>
 
 namespace mrdocs {
@@ -28,7 +29,7 @@ struct NoexceptInfo
 {
     /** Whether a noexcept-specifier was user-written.
     */
-    bool Implicit = true;
+    bool IsUserWritten = false;
 
     /** The evaluated exception specification.
     */
@@ -43,6 +44,11 @@ struct NoexceptInfo
     auto operator<=>(NoexceptInfo const&) const = default;
 };
 
+MRDOCS_DESCRIBE_STRUCT(
+    NoexceptInfo,
+    (),
+    (IsUserWritten, Kind, Operand))
+
 /** Convert NoexceptInfo to a string.
 
     @param info The noexcept-specifier information.
@@ -62,18 +68,6 @@ toString(
     bool resolved = false,
     bool implicit = false);
 
-/** Convert a NoexceptInfo to a DOM value.
-*/
-inline
-void
-tag_invoke(
-    dom::ValueFromTag tag,
-    dom::Value& v,
-    NoexceptInfo const& info)
-{
-    v = toString(info, false, false);
-}
-
 } // mrdocs
 
 #endif

include/mrdocs/Metadata/Specifiers/NoexceptKind.hpp

@@ -13,8 +13,7 @@
 #define MRDOCS_API_METADATA_SPECIFIERS_NOEXCEPTKIND_HPP
 
 #include <mrdocs/Platform.hpp>
-#include <mrdocs/Dom/String.hpp>
-#include <string>
+#include <mrdocs/Support/Describe.hpp>
 
 namespace mrdocs {
 
@@ -33,11 +32,7 @@ enum class NoexceptKind
     Dependent
 };
 
-/** Convert a noexcept kind to its string form.
-*/
-MRDOCS_DECL
-dom::String
-toString(NoexceptKind kind) noexcept;
+MRDOCS_DESCRIBE_ENUM(NoexceptKind, False, True, Dependent)
 
 } // mrdocs
 

include/mrdocs/Support/MergeReflectedType.hpp

@@ -95,13 +95,12 @@ isPlaceholderType(Polymorphic<Type> const& t);
     4.  `Polymorphic<Type>` — take if placeholder (AutoType or blank
                              NamedType)
     5.  `Polymorphic<Name>` — take if Identifier is empty
-    6.  `.Implicit` types   — take if dst is implicit
-    7.  `Optional<T>`       — take if disengaged; recursive merge
+    6.  `Optional<T>`       — take if disengaged; recursive merge
                              if both engaged and T has `merge()`
-    8.  `enum`              — take if zero-initialized
-    9.  `string`            — take if empty
-    10. `vector<T>` with `==` — dedup-append
-    11. `vector<T>` fallback — take if dst is empty
+    7.  `enum`              — take if zero-initialized
+    8.  `string`            — take if empty
+    9.  `vector<T>` with `==` — dedup-append
+    10. `vector<T>` fallback — take if dst is empty
 
     Returns `false` only for types none of the above handles.
 */
@@ -152,16 +151,6 @@ mergeByType(T& dst, T&& src)
         }
         return true;
     }
-    // Types with .Implicit flag (NoexceptInfo, ExplicitInfo):
-    // take src if dst is still implicit (compiler-generated).
-    else if constexpr (requires(T const& t) { { t.Implicit } -> std::convertible_to<bool>; })
-    {
-        if (dst.Implicit)
-        {
-            dst = std::move(src);
-        }
-        return true;
-    }
     // Optional<T>: take if disengaged; recursive merge if both
     // engaged and the value type has a merge() function.
     else if constexpr (is_optional_v<T>)

mrdocs.rnc

@@ -95,6 +95,23 @@ grammar
 
     TableAlignmentKind = "left" | "center" | "right"
 
+    NoexceptKind = "false" | "true" | "dependent"
+
+    #---------------------------------------------
+    # noexcept specification
+    #
+    # Emitted only when a noexcept-specifier is user-written
+    # (implicit specifications are skipped). The operand holds
+    # the expression as written, when present.
+    #---------------------------------------------
+
+    NoexceptSpec =
+        element noexcept
+        {
+            element kind { NoexceptKind },
+            element operand { text }?
+        }
+
     #---------------------------------------------
     # Name (used inside types, not for symbol names)
     #---------------------------------------------
@@ -187,7 +204,7 @@ grammar
             TypeBase,
             AnyType*,
             element ref-qualifier { text }?,
-            element exception-spec { text }?,
+            NoexceptSpec?,
             element is-variadic { Bool }?
         }
 
@@ -420,7 +437,7 @@ grammar
             Param*,
             TemplateInfo?,
             element func-class { FunctionClass }?,
-            element noexcept { text }?,
+            NoexceptSpec?,
             element requires { text }?,
             element is-variadic { Bool }?,
             element is-defaulted { Bool }?,

share/mrdocs/addons/generator/adoc/partials/markup/see-below.adoc.hbs

@@ -0,0 +1 @@
+pass:q[_see-below_]

share/mrdocs/addons/generator/adoc/partials/symbol.adoc.hbs

@@ -167,6 +167,16 @@
 | {{> symbol/qualified-name . }}
 {{/each}}
 |===
+{{/if}}
+{{/if}}
+{{! noexcept specification — only for dependent operands; constant
+    expressions like noexcept(true)/noexcept(false) are shown inline
+    in the signature and need no separate section. }}
+{{#if (eq symbol.noexcept.kind "dependent")}}
+{{#if symbol.noexcept.operand}}
+{{#> markup/dynamic-level-h }}noexcept Specification{{/markup/dynamic-level-h~}}
+`noexcept` when `{{symbol.noexcept.operand}}`.
+
 {{/if}}
 {{/if}}
 {{! Exceptions }}

share/mrdocs/addons/generator/common/partials/symbol/signature/function.hbs

@@ -10,7 +10,8 @@
 {{/if~}}
 {{#if isVirtual}}virtual
 {{/if~}}
-{{#if explicit}}{{explicit}}
+{{#if explicit.isUserWritten}}
+    {{~#if explicit.operand}}explicit({{explicit.operand}}){{else if (eq explicit.kind "true")}}explicit{{/if}}
 {{/if~}}
 {{#if (eq funcClass "normal")}}{{>type/declarator-prefix returnType}}
 {{/if~}}
@@ -31,7 +32,9 @@
 {{~#if isConst}} const{{/if~}}
 {{#if isVolatile}} volatile{{/if~}}
 {{#if refQualifier}} {{refQualifier}}{{/if~}}
-{{#if noexcept}} {{noexcept}}{{/if~}}
+{{~#if noexcept.isUserWritten~}}
+    {{~#if (eq noexcept.kind "dependent")}} noexcept({{> markup/see-below }}){{else if noexcept.operand}} noexcept({{noexcept.operand}}){{else if (eq noexcept.kind "true")}} noexcept{{/if~}}
+{{~/if~}}
 {{#if (eq funcClass "normal")}}{{>type/declarator-suffix returnType}}{{/if~}}
 {{#if requires}}
 

share/mrdocs/addons/generator/common/partials/type/declarator-suffix.hbs

@@ -37,8 +37,10 @@
     {{~#if cv-qualifiers}} {{cv-qualifiers}}{{/if~}}
     {{! Refqualifiers as "&" or "&&" ~}}
     {{#if (eq refQualifier "lvalue")}} &{{else if (eq refQualifier "rvalue")}} &&{{/if~}}
-    {{! Exception spec as literal string ~}}
-    {{#if exceptionSpec}} {{exceptionSpec}}{{/if~}}
+    {{! noexcept specification with "see-below" placeholder for dependent operands ~}}
+    {{~#if exceptionSpec.isUserWritten~}}
+        {{~#if (eq exceptionSpec.kind "dependent")}} noexcept({{> markup/see-below }}){{else if exceptionSpec.operand}} noexcept({{exceptionSpec.operand}}){{else if (eq exceptionSpec.kind "true")}} noexcept{{/if~}}
+    {{~/if~}}
     {{! Declarator suffix of the return type ~}}
     {{~>type/declarator-suffix returnType link-components-impl=link-components-impl~}}
 {{/if}}