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

[gennaroprota]

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.

[github-actions]

🚧 Danger.js checks for MrDocs are experimental; expect some rough edges while we tune the rules.

✨ Highlights

• 🧪 Existing golden tests changed (behavior likely shifted)

🧾 Changes by Scope

Scope	Lines Δ%	Lines Δ	Lines +	Lines -	Files Δ	Files +	Files ~	Files ↔	Files -
🥇 Golden Tests	69%	963	963	-	17	4	13	-	-
🧪 Unit Tests	15%	215	209	6	2	1	1	-	-
🛠️ Source	12%	171	76	95	17	2	15	-	-
🏗️ Build	3%	44	40	4	1	-	1	-	-
Total	100%	1393	1288	105	37	7	30	-	-

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

🔝 Top Files

• test-files/golden-tests/symbols/function/noexcept.xml (Golden Tests): 346 lines Δ (+346 / -0)
• src/test/lib/Metadata/Specifiers.cpp (Unit Tests): 203 lines Δ (+203 / -0)
• test-files/golden-tests/symbols/function/noexcept.html (Golden Tests): 194 lines Δ (+194 / -0)

Generated by 🚫 dangerJS against cc90113

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 81.89%. Comparing base (a3366b0) to head (cc90113).

Additional details and impacted files

@@             Coverage Diff             @@
##           develop    #1180      +/-   ##
===========================================
+ Coverage    78.82%   81.89%   +3.07%     
===========================================
  Files          308       33     -275     
  Lines        32157     2983   -29174     
  Branches      6456      691    -5765     
===========================================
- Hits         25347     2443   -22904     
+ Misses        4446      373    -4073     
+ Partials      2364      167    -2197     

Flag	Coverage Δ
bootstrap	81.89% <ø> (ø)
cpp	?

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]

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-04-27 10:53:47 UTC

[alandefreitas]

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

[gennaroprota]

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]

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]

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]

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