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

gennaroprota · gennaroprota · commit 7ee2a4e83d5c · 2026-04-22T17:04:04.000+02:00
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.
diff --git a/include/mrdocs/Metadata/Specifiers/NoexceptInfo.hpp b/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 {
@@ -43,6 +44,11 @@ struct NoexceptInfo
     auto operator<=>(NoexceptInfo const&) const = default;
 };
 
+MRDOCS_DESCRIBE_STRUCT(
+    NoexceptInfo,
+    (),
+    (Implicit, 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
diff --git a/include/mrdocs/Metadata/Specifiers/NoexceptKind.hpp b/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
 
diff --git a/mrdocs.rnc b/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 }?,
diff --git a/share/mrdocs/addons/generator/adoc/partials/markup/see-below.adoc.hbs b/share/mrdocs/addons/generator/adoc/partials/markup/see-below.adoc.hbs
@@ -0,0 +1 @@
+pass:q[_see-below_]
diff --git a/share/mrdocs/addons/generator/adoc/partials/symbol.adoc.hbs b/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 }}
diff --git a/share/mrdocs/addons/generator/common/partials/symbol/signature/function.hbs b/share/mrdocs/addons/generator/common/partials/symbol/signature/function.hbs
@@ -31,7 +31,9 @@
 {{~#if isConst}} const{{/if~}}
 {{#if isVolatile}} volatile{{/if~}}
 {{#if refQualifier}} {{refQualifier}}{{/if~}}
-{{#if noexcept}} {{noexcept}}{{/if~}}
+{{~#unless noexcept.implicit~}}
+    {{~#if (eq noexcept.kind "dependent")}} noexcept({{> markup/see-below }}){{else if noexcept.operand}} noexcept({{noexcept.operand}}){{else if (eq noexcept.kind "true")}} noexcept{{/if~}}
+{{~/unless~}}
 {{#if (eq funcClass "normal")}}{{>type/declarator-suffix returnType}}{{/if~}}
 {{#if requires}}
 
diff --git a/share/mrdocs/addons/generator/common/partials/type/declarator-suffix.hbs b/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 ~}}
+    {{~#unless exceptionSpec.implicit~}}
+        {{~#if (eq exceptionSpec.kind "dependent")}} noexcept({{> markup/see-below }}){{else if exceptionSpec.operand}} noexcept({{exceptionSpec.operand}}){{else if (eq exceptionSpec.kind "true")}} noexcept{{/if~}}
+    {{~/unless~}}
     {{! Declarator suffix of the return type ~}}
     {{~>type/declarator-suffix returnType link-components-impl=link-components-impl~}}
 {{/if}}
diff --git a/share/mrdocs/addons/generator/html/partials/markup/see-below.html.hbs b/share/mrdocs/addons/generator/html/partials/markup/see-below.html.hbs
@@ -0,0 +1 @@
+<em>see-below</em>
diff --git a/share/mrdocs/addons/generator/html/partials/symbol.html.hbs b/share/mrdocs/addons/generator/html/partials/symbol.html.hbs
@@ -231,6 +231,17 @@
 {{/if}}
 </div>
 
+{{/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}}
+<div>
+{{#> markup/dynamic-level-h level=2 }}noexcept Specification{{/markup/dynamic-level-h~}}
+<p><code>noexcept</code> when <code>{{symbol.noexcept.operand}}</code>.</p>
+</div>
+{{/if}}
 {{/if}}
 {{! Exceptions }}
 {{#if symbol.doc.exceptions}}
diff --git a/src/lib/Gen/xml/XMLWriter.cpp b/src/lib/Gen/xml/XMLWriter.cpp
@@ -14,6 +14,7 @@
 
 #include "XMLWriter.hpp"
 #include <mrdocs/Metadata/Expression.hpp>
+#include <mrdocs/Metadata/Specifiers/NoexceptInfo.hpp>
 #include <mrdocs/Metadata/Type.hpp>
 #include <mrdocs/Metadata/Template.hpp>
 #include <mrdocs/Metadata/DocComment.hpp>
@@ -180,6 +181,8 @@ XMLWriter::writeElement(std::string_view tag, T const& value)
         { if (value.empty()) return; }
     else if constexpr (std::is_base_of_v<ExprInfo, Type>)
         { if (value.Written.empty()) return; }
+    else if constexpr (std::is_same_v<Type, NoexceptInfo>)
+        { if (value.Implicit) return; }
 
     // Primitives inline, compounds wrapped.
     if constexpr (std::is_base_of_v<ExprInfo, Type>)
diff --git a/src/lib/Metadata/Specifiers.cpp b/src/lib/Metadata/Specifiers.cpp
@@ -66,18 +66,6 @@ dom::String toString(ExplicitKind kind) noexcept
     }
 }
 
-dom::String toString(NoexceptKind kind) noexcept
-{
-    switch(kind)
-    {
-    case NoexceptKind::False:     return "";
-    case NoexceptKind::True:      return "noexcept";
-    case NoexceptKind::Dependent: return "noexcept(...)";
-    default:
-        MRDOCS_UNREACHABLE();
-    }
-}
-
 dom::String
 toString(
     NoexceptInfo const& info,
diff --git a/test-files/golden-tests/config/extract-friends/extract-friends.xml b/test-files/golden-tests/config/extract-friends/extract-friends.xml
@@ -140,6 +140,9 @@
     <name>rhs</name>
   </param>
   <func-class>normal</func-class>
+  <noexcept>
+    <kind>true</kind>
+  </noexcept>
   <is-record-method>1</is-record-method>
   <is-const>1</is-const>
 </function>
diff --git a/test-files/golden-tests/config/extract-friends/no-extract-friends.xml b/test-files/golden-tests/config/extract-friends/no-extract-friends.xml
@@ -140,6 +140,9 @@
     <name>rhs</name>
   </param>
   <func-class>normal</func-class>
+  <noexcept>
+    <kind>true</kind>
+  </noexcept>
   <is-record-method>1</is-record-method>
   <is-const>1</is-const>
 </function>
diff --git a/test-files/golden-tests/javadoc/copydoc/operator-param.xml b/test-files/golden-tests/javadoc/copydoc/operator-param.xml
@@ -156,6 +156,9 @@
     <name>ch</name>
   </param>
   <func-class>normal</func-class>
+  <noexcept>
+    <kind>true</kind>
+  </noexcept>
   <is-record-method>1</is-record-method>
   <is-const>1</is-const>
 </function>
@@ -221,6 +224,9 @@
     <name>ch</name>
   </param>
   <func-class>normal</func-class>
+  <noexcept>
+    <kind>true</kind>
+  </noexcept>
   <is-record-method>1</is-record-method>
   <is-const>1</is-const>
 </function>
diff --git a/test-files/golden-tests/javadoc/inline/styled.xml b/test-files/golden-tests/javadoc/inline/styled.xml
@@ -203,6 +203,9 @@
     <name>other</name>
   </param>
   <func-class>normal</func-class>
+  <noexcept>
+    <kind>true</kind>
+  </noexcept>
   <is-record-method>1</is-record-method>
   <is-const>1</is-const>
 </function>
diff --git a/test-files/golden-tests/snippets/function_object.xml b/test-files/golden-tests/snippets/function_object.xml
@@ -92,6 +92,9 @@
     <name>x</name>
   </param>
   <func-class>normal</func-class>
+  <noexcept>
+    <kind>true</kind>
+  </noexcept>
   <is-record-method>1</is-record-method>
   <is-const>1</is-const>
 </function>
@@ -150,6 +153,9 @@
     <name>x</name>
   </param>
   <func-class>normal</func-class>
+  <noexcept>
+    <kind>true</kind>
+  </noexcept>
   <function-object-impl>7X78dvKaHCvXfNokuB9sZf6Fq4o=</function-object-impl>
 </function>
 </mrdocs>
diff --git a/test-files/golden-tests/snippets/is_prime.xml b/test-files/golden-tests/snippets/is_prime.xml
@@ -92,5 +92,8 @@
     <name>n</name>
   </param>
   <func-class>normal</func-class>
+  <noexcept>
+    <kind>true</kind>
+  </noexcept>
 </function>
 </mrdocs>
diff --git a/test-files/golden-tests/snippets/terminate.xml b/test-files/golden-tests/snippets/terminate.xml
@@ -60,6 +60,9 @@
     </name>
   </named>
   <func-class>normal</func-class>
+  <noexcept>
+    <kind>true</kind>
+  </noexcept>
   <is-no-return>1</is-no-return>
   <attributes>noreturn</attributes>
 </function>
diff --git a/test-files/golden-tests/symbols/function/explicit-ctor.xml b/test-files/golden-tests/symbols/function/explicit-ctor.xml
@@ -227,6 +227,9 @@
     <name>other</name>
   </param>
   <func-class>constructor</func-class>
+  <noexcept>
+    <kind>true</kind>
+  </noexcept>
   <is-record-method>1</is-record-method>
 </function>
 <function>
@@ -502,6 +505,9 @@
     <name>other</name>
   </param>
   <func-class>constructor</func-class>
+  <noexcept>
+    <kind>true</kind>
+  </noexcept>
   <is-record-method>1</is-record-method>
 </function>
 <function>
@@ -765,6 +771,9 @@
     <name>other</name>
   </param>
   <func-class>constructor</func-class>
+  <noexcept>
+    <kind>true</kind>
+  </noexcept>
   <is-record-method>1</is-record-method>
 </function>
 <function>
@@ -1028,6 +1037,9 @@
     <name>other</name>
   </param>
   <func-class>constructor</func-class>
+  <noexcept>
+    <kind>true</kind>
+  </noexcept>
   <is-record-method>1</is-record-method>
 </function>
 <function>
diff --git a/test-files/golden-tests/symbols/function/mem-fn.xml b/test-files/golden-tests/symbols/function/mem-fn.xml
diff --git a/test-files/golden-tests/symbols/function/noexcept.adoc b/test-files/golden-tests/symbols/function/noexcept.adoc
diff --git a/test-files/golden-tests/symbols/function/noexcept.cpp b/test-files/golden-tests/symbols/function/noexcept.cpp
diff --git a/test-files/golden-tests/symbols/function/noexcept.html b/test-files/golden-tests/symbols/function/noexcept.html
diff --git a/test-files/golden-tests/symbols/function/noexcept.xml b/test-files/golden-tests/symbols/function/noexcept.xml
