feat: render long noexcept specifications as noexcept(see-below) by gennaroprota · Pull Request #1180 · cppalliance/mrdocs

gennaroprota · 2026-04-22T15:00:45Z

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.

[danger skip docs].

Summary

Renders long noexcept specifications as noexcept(see-below) and pulls the actual condition into a dedicated "noexcept Specification" section of the exposition, so the function signature stays readable when the condition is a dependent expression. Closes #1103.

Before this PR, 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 keyword in a wall of trait expressions. After this PR, the same declaration renders as

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

and the condition appears under a separate "noexcept Specification" subsection alongside the declaration. The section is intentionally separate from the existing "Exceptions" section, which continues to cover @throws documentation.

The implementation lives mostly in the Handlebars template layer. The C++ side adds a small helper surface in include/mrdocs/Support/Handlebars.hpp (implemented in src/lib/Support/Handlebars.cpp); the existing function-signature, declarator-suffix, and per-format symbol partials under share/mrdocs/addons/ are updated to consume it.

Changes

Source: New Handlebars helper added in src/lib/Support/Handlebars.cpp and exposed via the public include/mrdocs/Support/Handlebars.hpp (additive). Templates updated under share/mrdocs/addons/: common/partials/symbol/signature/function.hbs and common/partials/type/declarator-suffix.hbs decide when to print (see-below); adoc/partials/symbol.adoc.hbs and html/partials/symbol.html.hbs render the new "noexcept Specification" section in their respective output formats.
Tests: New src/test/lib/Metadata/NoexceptInfo.cpp (118 lines) covers the underlying noexcept-info classification — which operands stay inline vs. get redirected to the see-below section.
Golden tests: New test-files/golden-tests/symbols/function/noexcept.{cpp,xml,html,adoc} fixture exercises the see-below path end-to-end across all three output formats.
Breaking changes: None at the user-facing CLI; configuration is unchanged. The generated XML / HTML / adoc output for functions with long, dependent noexcept specifications changes — downstream tooling that scrapes function signatures and expects the full inlined condition will need to also read the new "noexcept Specification" section.

Testing

src/test/lib/Metadata/NoexceptInfo.cpp is the unit-level coverage for the classification rule (when an operand is short enough to inline vs. long or dependent enough to redirect to the see-below section).
test-files/golden-tests/symbols/function/noexcept.{cpp,xml,html,adoc} is the end-to-end coverage across all three output formats; any regression in either the classification or the template rendering will fail the golden output.
No CI workflow changes needed — the existing unit-test and golden-test jobs already cover both layers on every build.

Documentation

No user-facing documentation page is added ([danger skip docs]). The change is a rendering improvement for generated output: it does not surface a new option, flag, or configuration knob a user would need to look up. The new "noexcept Specification" section is self-describing in the generated output.

github-actions · 2026-04-22T15:01:12Z

✨ Highlights

🧪 New golden tests added

🧾 Changes by Scope

Scope	Lines Δ%	Lines Δ	Lines +	Lines -	Files Δ	Files +	Files ~	Files ↔	Files -
🥇 Golden Tests	80%	707	707	-	4	4	-	-	-
🧪 Unit Tests	13%	118	118	-	1	1	-	-	-
🛠️ Source	7%	61	58	3	6	-	6	-	-
Total	100%	886	883	3	11	5	6	-	-

Legend: Files + (added), Files ~ (modified), Files ↔ (renamed), Files - (removed)

🔝 Top Files

test-files/golden-tests/symbols/function/noexcept.xml (Golden Tests): 316 lines Δ (+316 / -0)
test-files/golden-tests/symbols/function/noexcept.html (Golden Tests): 194 lines Δ (+194 / -0)
test-files/golden-tests/symbols/function/noexcept.adoc (Golden Tests): 159 lines Δ (+159 / -0)

Generated by 🚫 dangerJS against d4b4a4f

codecov · 2026-04-22T15:01:37Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 82.12%. Comparing base (ab5f412) to head (d4b4a4f).

Additional details and impacted files

@@           Coverage Diff            @@
##           develop    #1180   +/-   ##
========================================
  Coverage    82.12%   82.12%           
========================================
  Files           33       33           
  Lines         3149     3149           
  Branches       734      734           
========================================
  Hits          2586     2586           
  Misses         387      387           
  Partials       176      176

Flag	Coverage Δ
bootstrap	`82.12% <ø> (ø)`

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

cppalliance-bot · 2026-04-22T15:09:07Z

An automated preview of the documentation is available at https://1180.mrdocs.prtest2.cppalliance.org/index.html

If more commits are pushed to the pull request, the docs will rebuild at the same URL.

2026-05-14 09:09:01 UTC

alandefreitas · 2026-04-23T19:56:30Z

What criteria did we end up with to consider the condition long?

gennaroprota · 2026-04-24T07:34:12Z

There's no length check. The rule ended up being noexcept.kind == dependent.

Non-dependent specifications do carry text but, in practice, that's empty or literally true/false, so the inline form stays short. Dependent operands are (again, in practice) the only ones that may grow long, and are currently always rendered with "see-below", even when "short". Do you want to tweak that?

alandefreitas · 2026-04-24T14:36:20Z

I'm not clear on what this means. OK. Questions:

Aren't these just specifications dependent on template parameters?
I don't understand what this is a proxy for. Are you trying to infer the size from the specification kind?
Why is this a good proxy for that (size?)? It seems very easy to come up with a counterexample.
And why would we look at a proxy when the thing the proxy is a proxy for (size?) is readily available?
Also, I don't understand how this compares to whatever cppreference does.

For example, if noexcept(std::default_constructible<T>) were dependent and rendered in a way that's much harder to read, I don't see how that's a good thing.

I mean, to some extent, the strategy ended up being, in practice, "almost always use see-below". And it's mostly coherent with cppreference it uses see-below even for things like noexcept(std::is_nothrow_move_constructible_v<E>). https://en.cppreference.com/cpp/utility/expected/expected

But I'm not sure this is a good thing for mrdocs because cppreference inherited this format from the old times when concepts weren't a thing (so the other rules were already there as a rule at the bottom of the page) and is edited manually (so they can always go back and forth and don't have to justify their thresholds precisely).

On the other hand, for MrDocs, when we look at the nature of user complaints, it's usually only about the cases when it's not legible. This is typically when it's too large to render or when it uses lots of implementation details. In cases where it's something like noexcept(std::is_nothrow_move_constructible_v<E>), users actually see mrdocs as an improvement over cppreference.

What's interesting is if you look at https://en.cppreference.com/cpp/utility/expected/expected, you'll see the explicit specifications are actually inline when they're short. Their rule is not the same, and I assume it's because they don't have to maintain their own historical precedent in this case.

gennaroprota · 2026-04-24T14:54:22Z

OK, fixing an arbitrary length limit didn't look "right" to me, so I wanted something more logical and not arbitrary, like "dependent"/"non-dependent". But that's a weak proxy. If length is what users complain about (and we have that as info.Operand.size()) let's switch to a length threshold (say 40 characters): Inline when <= 40, "see-below" when longer. Does that work for you?

alandefreitas · 2026-04-24T14:57:31Z

Yes. That doesn't seem arbitrary at all. But please confirm what this looks like when rendered in adoc and html.

alandefreitas · 2026-05-12T19:12:51Z

    /** Whether an explicit-specifier was user-written.
    */
-    bool Implicit = true;
+    bool IsUserWritten = false;


Is this change really valuable? I think the other name came from Krystian, but I think it makes sense. Explicit/Implicit carries more semantic weight than UserWritten to me. Because the user chose to write what he chose to write anyway.

alandefreitas · 2026-05-12T19:13:12Z

    /** Whether a noexcept-specifier was user-written.
    */
-    bool Implicit = true;
+    bool IsUserWritten = false;


alandefreitas · 2026-05-12T19:14:33Z

+        `noexcept(see-below)` plus a separate specification section,
+        instead of inline in the signature.
+    */
+    bool OperandIsLong = false;


Oh... This should be at the presentation level, not at this level in the handlebars templates. If we open this Pandora’s box, we can never close it again.

alandefreitas · 2026-05-12T19:21:19Z

  </param>
  <func-class>normal</func-class>
+  <noexcept>
+    <is-user-written>1</is-user-written>


It seems like we're not representing booleans correctly in XML.

Yes. See PR #1200.

alandefreitas · 2026-05-12T19:21:24Z

  <func-class>normal</func-class>
+  <noexcept>
+    <is-user-written>1</is-user-written>
+    <kind>true</kind>


This also seems wrong.

That's actually correct, although confusing, because NoexceptKind is defined as:

enum class NoexceptKind { /** Potentially-throwing exception specification */ False = 0, /** Non-throwing exception specification */ True, /** Dependent exception specification */ Dependent };

alandefreitas · 2026-05-12T19:23:42Z

+    T&) noexcept(pass:q[_see-below_]);
+----
+
+=== noexcept Specification


Is this intentional?

Should it be "noexcept specification"? Or maybe "noexcept Specification"? What does cppreference use?

Cppreference puts everything under "Exceptions" (see e.g. https://en.cppreference.com/cpp/utility/expected/expected). In any case, MrDocs uses title case for section headings, so, if we keep that separate section, the title must say "Specification", with an uppercase "S".

alandefreitas · 2026-05-13T22:10:50Z

No user-facing documentation page is added ([danger skip docs]). The change is a rendering improvement for generated output: it does not surface a new option, flag, or configuration knob a user would need to look up. The new "noexcept Specification" section is self-describing in the generated output.

About this point, I noticed MrDocs supports lots of very nice C++ idioms that make life very convenient, and most of them are not documented. I'm noticing this as I'm working on this presentation about MrDocs. Maybe that's how this could go into the documentation. We could have a page or section for C++ idioms, and over time we can try to categorize them, and then we just have a reference of all the nice things MrDocs can do, and that's going to be one of them.

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 operands longer than 40 characters 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 cppalliance#1103.

gennaroprota force-pushed the feat/describe_noexcept_conditions_naturally branch 2 times, most recently from 1e52e6d to 7ee2a4e Compare April 22, 2026 15:04

gennaroprota force-pushed the feat/describe_noexcept_conditions_naturally branch 2 times, most recently from 4fa1508 to 4b717a2 Compare April 23, 2026 13:49

gennaroprota changed the title ~~feat: render dependent noexcept specifications as noexcept(see-below)~~ feat: render long noexcept specifications as noexcept(see-below) Apr 24, 2026

gennaroprota force-pushed the feat/describe_noexcept_conditions_naturally branch 3 times, most recently from 139128a to cc90113 Compare April 27, 2026 14:03

gennaroprota force-pushed the feat/describe_noexcept_conditions_naturally branch from cc90113 to 6ff8c77 Compare May 4, 2026 09:11

alandefreitas reviewed May 12, 2026

View reviewed changes

gennaroprota added no-docs-needed and removed no-docs-needed labels May 13, 2026

gennaroprota force-pushed the feat/describe_noexcept_conditions_naturally branch from 6ff8c77 to 17a78f6 Compare May 13, 2026 07:52

gennaroprota force-pushed the feat/describe_noexcept_conditions_naturally branch from 17a78f6 to d4b4a4f Compare May 14, 2026 09:00

Conversation

gennaroprota commented Apr 22, 2026 • edited by alandefreitas Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

Testing

Documentation

Uh oh!

github-actions Bot commented Apr 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✨ Highlights

🧾 Changes by Scope

🔝 Top Files

Uh oh!

codecov Bot commented Apr 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

cppalliance-bot commented Apr 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

alandefreitas commented Apr 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

gennaroprota commented Apr 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

alandefreitas commented Apr 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

gennaroprota commented Apr 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

alandefreitas commented Apr 24, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gennaroprota May 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

alandefreitas commented May 13, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

gennaroprota commented Apr 22, 2026 •

edited by alandefreitas

Loading

github-actions Bot commented Apr 22, 2026 •

edited

Loading

codecov Bot commented Apr 22, 2026 •

edited

Loading

cppalliance-bot commented Apr 22, 2026 •

edited

Loading

alandefreitas commented Apr 23, 2026 •

edited

Loading

gennaroprota commented Apr 24, 2026 •

edited

Loading

alandefreitas commented Apr 24, 2026 •

edited

Loading

gennaroprota commented Apr 24, 2026 •

edited

Loading

gennaroprota May 13, 2026 •

edited

Loading