From 13c4230ecd2c2f78185b6b2394ba07728198a464 Mon Sep 17 00:00:00 2001 From: Gennaro Prota Date: Wed, 23 Sep 2026 15:52:26 +0200 Subject: [PATCH] feat(generators): document function parameters and template parameters right after the description We documented a symbol's template parameters and function parameters near the end of the symbol's page: on a class page, after the members and the non-member functions; on a function page, after the exceptions and the return value. Member descriptions often refer to the template parameters, so that order was at best inconvenient for class templates. It also seemed unnatural for functions. Both sections now appear right after the description on every kind of page, as they do on cppreference.com. Fixes #1231. --- .../generator/common/partials/symbol.hbs | 4 +- docs/website/index.html | 92 +++++++++---------- .../extensions/ghostwriter/reference.adoc | 8 +- .../fixtures/generator/hbs/macros/macros.adoc | 8 +- .../fixtures/generator/hbs/macros/macros.html | 8 +- .../noexcept-limit.adoc | 8 +- .../noexcept-limit.html | 8 +- .../fixtures/snippets/commands/copydoc.adoc | 16 ++-- .../fixtures/snippets/commands/regex.adoc | 8 +- .../fixtures/snippets/commands/resample.adoc | 8 +- .../commands/template-parameters.adoc | 8 +- .../inherited-members-specialization.adoc | 16 ++-- .../name-filters/name-filters.adoc | 16 ++-- .../private-symbols/private-symbols.adoc | 8 +- tests/golden/fixtures/snippets/distance.adoc | 8 +- .../fixtures/snippets/function_object.adoc | 8 +- .../fixtures/snippets/insert_sorted.adoc | 22 ++--- tests/golden/fixtures/snippets/is_prime.adoc | 8 +- .../fixtures/snippets/landing/sqrt.adoc | 16 ++-- .../fixtures/snippets/landing/sqrt.html | 18 ++-- tests/golden/fixtures/snippets/lock_file.adoc | 18 ++-- .../auto-function-metadata.adoc | 24 ++--- .../auto-function-objects.adoc | 8 +- .../exclude-symbols/exclude-symbols.adoc | 8 +- .../extract-friends/extract-friends.adoc | 8 +- .../implementation-defined.adoc | 8 +- .../snippets/options/see-below/see-below.adoc | 8 +- .../sort-members-assignment-1st.adoc | 16 ++-- .../sort-members-relational-last.adoc | 16 ++-- tests/golden/fixtures/snippets/sqrt.adoc | 26 +++--- .../fixtures/symbols/function/extern-c.adoc | 8 +- .../implicit-specialization-dependency.adoc | 44 ++++----- 32 files changed, 244 insertions(+), 244 deletions(-) diff --git a/data/mrdocs/addons/generator/common/partials/symbol.hbs b/data/mrdocs/addons/generator/common/partials/symbol.hbs index 9f00494c505..7ec8c505d53 100644 --- a/data/mrdocs/addons/generator/common/partials/symbol.hbs +++ b/data/mrdocs/addons/generator/common/partials/symbol.hbs @@ -18,6 +18,8 @@ {{> symbol/section/attribute-admonitions ~}} {{> symbol/section/function-object-admonition}} {{> symbol/section/description}} +{{> symbol/section/template-parameters}} +{{> symbol/section/parameters}} {{> symbol/section/base-classes}} {{> symbol/section/protected-base-classes}} {{> symbol/section/members}} @@ -31,8 +33,6 @@ {{> symbol/section/noexcept-specification}} {{> symbol/section/exceptions}} {{> symbol/section/return-value}} -{{> symbol/section/template-parameters}} -{{> symbol/section/parameters}} {{> symbol/section/preconditions}} {{> symbol/section/postconditions}} {{> symbol/section/see-also}} diff --git a/docs/website/index.html b/docs/website/index.html index 42f30072c17..7a1908da263 100644 --- a/docs/website/index.html +++ b/docs/website/index.html @@ -309,10 +309,6 @@

Synopsis

Description

This function returns the distance between two points according to the Euclidean distance formula.

-
-

Return Value

-

The distance between the two points

-

Parameters

@@ -327,6 +323,10 @@

Parameters

+
+

Return Value

+

The distance between the two points

+
@@ -382,6 +382,18 @@

Synopsis

std::vector<int>& v, int value); +
+

Parameters

+ + + + + + + + +
NameDescription
vThe sorted vector to insert into.
valueThe value to insert.
+

Exceptions

@@ -397,18 +409,6 @@

Exceptions

Return Value

An iterator to the inserted element.

-
-

Parameters

-
- - - - - - - -
NameDescription
vThe sorted vector to insert into.
valueThe value to insert.
-

Preconditions

-
-

Exceptions

- - - - - - - -
NameThrown on
std::invalid_argumentIf the input value is negative.
-
-
-

Return Value

-

The square root of the input value.

-

Template Parameters

@@ -519,6 +504,21 @@

Parameters

+
+

Exceptions

+ + + + + + + +
NameThrown on
std::invalid_argumentIf the input value is negative.
+
+
+

Return Value

+

The square root of the input value.

+
@@ -576,10 +576,6 @@

NOTE

This function is defined as an Algorithm Function Object (AFO).

-
-

Return Value

-

The absolute value of x.

-

Parameters

@@ -591,6 +587,10 @@

Parameters

+
+

Return Value

+

The absolute value of x.

+
@@ -675,6 +675,17 @@

Synopsis

Description

The lock is held until the returned object is destroyed.

+
+

Parameters

+ + + + + + + +
NameDescription
pathThe path of the file to lock.
+

Exceptions

@@ -695,17 +706,6 @@

NOTE

The return value should not be discarded.

-
-

Parameters

-
- - - - - - -
NameDescription
pathThe path of the file to lock.
-
diff --git a/examples/extensions/ghostwriter/reference.adoc b/examples/extensions/ghostwriter/reference.adoc index d6fc4cb2727..3dae3bb753e 100644 --- a/examples/extensions/ghostwriter/reference.adoc +++ b/examples/extensions/ghostwriter/reference.adoc @@ -195,10 +195,6 @@ distance( The value is symmetric in its arguments and is zero exactly when the two points coincide, so it works well as the basis for an equality‐with‐tolerance check. -=== Return Value - -The straight‐line distance between `a` and `b`. - === Parameters [cols="1,4"] @@ -210,5 +206,9 @@ The straight‐line distance between `a` and `b`. | The second point. |=== +=== Return Value + +The straight‐line distance between `a` and `b`. + [.small]#Created with https://www.mrdocs.com[MrDocs]# diff --git a/tests/golden/fixtures/generator/hbs/macros/macros.adoc b/tests/golden/fixtures/generator/hbs/macros/macros.adoc index 81621df1876..9cb255da107 100644 --- a/tests/golden/fixtures/generator/hbs/macros/macros.adoc +++ b/tests/golden/fixtures/generator/hbs/macros/macros.adoc @@ -48,10 +48,6 @@ Declared in `<macros.cpp>` ---- -=== Return Value - -`x` clamped to the range. - === Parameters [cols="1,4"] @@ -65,6 +61,10 @@ Declared in `<macros.cpp>` | The upper bound. |=== +=== Return Value + +`x` clamped to the range. + [#EXAMPLE_LOG] == EXAMPLE_LOG diff --git a/tests/golden/fixtures/generator/hbs/macros/macros.html b/tests/golden/fixtures/generator/hbs/macros/macros.html index c2a74476a10..9a2a082d0ab 100644 --- a/tests/golden/fixtures/generator/hbs/macros/macros.html +++ b/tests/golden/fixtures/generator/hbs/macros/macros.html @@ -48,10 +48,6 @@

Synopsis

#define EXAMPLE_CLAMP(x, lo, hi)
-
-

Return Value

-

x clamped to the range.

-

Parameters

@@ -65,6 +61,10 @@

Parameters

+
+

Return Value

+

x clamped to the range.

+
diff --git a/tests/golden/fixtures/generator/hbs/noexcept-see-below-limit/noexcept-limit.adoc b/tests/golden/fixtures/generator/hbs/noexcept-see-below-limit/noexcept-limit.adoc index ae84f7a112b..44569a72308 100644 --- a/tests/golden/fixtures/generator/hbs/noexcept-see-below-limit/noexcept-limit.adoc +++ b/tests/golden/fixtures/generator/hbs/noexcept-see-below-limit/noexcept-limit.adoc @@ -32,10 +32,6 @@ swap( T& b) noexcept(/* see-below */); ---- -=== Exception specification - -This function is potentially-throwing unless `sizeof(T) > sizeof(int)`. - === Parameters [cols="1,4"] @@ -47,5 +43,9 @@ This function is potentially-throwing unless `sizeof(T) > sizeof(int)`. | second value |=== +=== Exception specification + +This function is potentially-throwing unless `sizeof(T) > sizeof(int)`. + [.small]#Created with https://www.mrdocs.com[MrDocs]# diff --git a/tests/golden/fixtures/generator/hbs/noexcept-see-below-limit/noexcept-limit.html b/tests/golden/fixtures/generator/hbs/noexcept-see-below-limit/noexcept-limit.html index 22822352a66..0bd1ac380ee 100644 --- a/tests/golden/fixtures/generator/hbs/noexcept-see-below-limit/noexcept-limit.html +++ b/tests/golden/fixtures/generator/hbs/noexcept-see-below-limit/noexcept-limit.html @@ -36,10 +36,6 @@

Synopsis

T& a, T& b) noexcept(/* see-below */);
-
-

Exception specification

-

This function is potentially-throwing unless sizeof(T) > sizeof(int).

-

Parameters

@@ -52,6 +48,10 @@

Parameters

+
+

Exception specification

+

This function is potentially-throwing unless sizeof(T) > sizeof(int).

+
diff --git a/tests/golden/fixtures/snippets/commands/copydoc.adoc b/tests/golden/fixtures/snippets/commands/copydoc.adoc index 9435c472040..d77be9edf37 100644 --- a/tests/golden/fixtures/snippets/commands/copydoc.adoc +++ b/tests/golden/fixtures/snippets/commands/copydoc.adoc @@ -18,10 +18,6 @@ b64_encode( unsigned int n); ---- -=== Return Value - -A null‐terminated base‐64 string. Owned by the caller. - === Parameters [cols="1,4"] @@ -33,6 +29,10 @@ A null‐terminated base‐64 string. Owned by the caller&perio | Number of bytes in `data`. |=== +=== Return Value + +A null‐terminated base‐64 string. Owned by the caller. + [#base64] == base64 @@ -50,10 +50,6 @@ base64( unsigned int n); ---- -=== Return Value - -A null‐terminated base‐64 string. Owned by the caller. - === Parameters [cols="1,4"] @@ -65,5 +61,9 @@ A null‐terminated base‐64 string. Owned by the caller&perio | Number of bytes in `data`. |=== +=== Return Value + +A null‐terminated base‐64 string. Owned by the caller. + [.small]#Created with https://www.mrdocs.com[MrDocs]# diff --git a/tests/golden/fixtures/snippets/commands/regex.adoc b/tests/golden/fixtures/snippets/commands/regex.adoc index cce6cc5a2f2..3b8cb9c26e5 100644 --- a/tests/golden/fixtures/snippets/commands/regex.adoc +++ b/tests/golden/fixtures/snippets/commands/regex.adoc @@ -34,10 +34,6 @@ Declared in `<regex.cpp>` bytecode(link:#regex[regex] const& re); ---- -=== Return Value - -The bytecode, in an implementation‐defined form. - === Parameters [cols="1,4"] @@ -47,6 +43,10 @@ The bytecode, in an implementation‐defined form. | A compiled regular expression. |=== +=== Return Value + +The bytecode, in an implementation‐defined form. + [#compile] == compile diff --git a/tests/golden/fixtures/snippets/commands/resample.adoc b/tests/golden/fixtures/snippets/commands/resample.adoc index f28567df99d..4e58c35ed6d 100644 --- a/tests/golden/fixtures/snippets/commands/resample.adoc +++ b/tests/golden/fixtures/snippets/commands/resample.adoc @@ -21,10 +21,6 @@ resample( Sample* out); ---- -=== Return Value - -The number of samples written to `out`. - === Template Parameters [cols="1,4"] @@ -49,5 +45,9 @@ The number of samples written to `out`. | Buffer that receives the resampled signal. |=== +=== Return Value + +The number of samples written to `out`. + [.small]#Created with https://www.mrdocs.com[MrDocs]# diff --git a/tests/golden/fixtures/snippets/commands/template-parameters.adoc b/tests/golden/fixtures/snippets/commands/template-parameters.adoc index fdccc61c050..a3a580f1a29 100644 --- a/tests/golden/fixtures/snippets/commands/template-parameters.adoc +++ b/tests/golden/fixtures/snippets/commands/template-parameters.adoc @@ -19,10 +19,6 @@ max_of( T const& b); ---- -=== Return Value - -the larger of two values. - === Template Parameters [cols="1,4"] @@ -32,5 +28,9 @@ the larger of two values. | A type that supports `operator<`. |=== +=== Return Value + +the larger of two values. + [.small]#Created with https://www.mrdocs.com[MrDocs]# diff --git a/tests/golden/fixtures/snippets/configuration/inherited-members-specialization/inherited-members-specialization.adoc b/tests/golden/fixtures/snippets/configuration/inherited-members-specialization/inherited-members-specialization.adoc index fff3dc743e3..b499e7fb54d 100644 --- a/tests/golden/fixtures/snippets/configuration/inherited-members-specialization/inherited-members-specialization.adoc +++ b/tests/golden/fixtures/snippets/configuration/inherited-members-specialization/inherited-members-specialization.adoc @@ -117,10 +117,6 @@ bool operator==(link:#version[version] const& other) const noexcept; ---- -=== Return Value - -`true` if the objects are equal, `false` otherwise - === Parameters [cols="1,4"] @@ -130,6 +126,10 @@ operator==(link:#version[version] const& other) const noexcept; | The right operand |=== +=== Return Value + +`true` if the objects are equal, `false` otherwise + [#version-operator_not_eq] == link:#version[version]::operator!= @@ -145,10 +145,6 @@ bool operator!=(link:#version[version] const& other) const noexcept; ---- -=== Return Value - -`true` if the objects are not equal, `false` otherwise - === Parameters [cols="1,4"] @@ -158,6 +154,10 @@ operator!=(link:#version[version] const& other) const noexcept; | The right operand |=== +=== Return Value + +`true` if the objects are not equal, `false` otherwise + [#version-major] == link:#version[version]::major diff --git a/tests/golden/fixtures/snippets/configuration/name-filters/name-filters.adoc b/tests/golden/fixtures/snippets/configuration/name-filters/name-filters.adoc index c4c0a289265..3b94c3a2f37 100644 --- a/tests/golden/fixtures/snippets/configuration/name-filters/name-filters.adoc +++ b/tests/golden/fixtures/snippets/configuration/name-filters/name-filters.adoc @@ -43,10 +43,6 @@ parse(char const* source); Validates `source` and returns the resulting value tree. -=== Return Value - -A parsed JSON document. - === Parameters [cols="1,4"] @@ -56,6 +52,10 @@ A parsed JSON document. | A null‐terminated UTF‐8 JSON document. |=== +=== Return Value + +A parsed JSON document. + [#jzon-validate] == jzon::validate @@ -75,10 +75,6 @@ validate(char const* source); Parses `source` without constructing a value tree, reporting only whether the input conforms to RFC 8259. -=== Return Value - -`true` if the document is syntactically valid JSON. - === Parameters [cols="1,4"] @@ -88,5 +84,9 @@ Parses `source` without constructing a value tree, reporting only whether the in | A null‐terminated UTF‐8 JSON document. |=== +=== Return Value + +`true` if the document is syntactically valid JSON. + [.small]#Created with https://www.mrdocs.com[MrDocs]# diff --git a/tests/golden/fixtures/snippets/configuration/private-symbols/private-symbols.adoc b/tests/golden/fixtures/snippets/configuration/private-symbols/private-symbols.adoc index 4b06e5b2e31..ed91b3c5ae0 100644 --- a/tests/golden/fixtures/snippets/configuration/private-symbols/private-symbols.adoc +++ b/tests/golden/fixtures/snippets/configuration/private-symbols/private-symbols.adoc @@ -40,10 +40,6 @@ scoped_context( The context stays attached until the returned token is destroyed. Hold it in `auto`; nested contexts stack and unwind in reverse order. -=== Return Value - -An opaque RAII token whose lifetime governs how long the pair stays attached. - === Parameters [cols="1,4"] @@ -55,6 +51,10 @@ An opaque RAII token whose lifetime governs how long the pair stays attached&per | The context value surfaced on each log line. |=== +=== Return Value + +An opaque RAII token whose lifetime governs how long the pair stays attached. + [#logr-set_encoder] == logr::set_encoder diff --git a/tests/golden/fixtures/snippets/distance.adoc b/tests/golden/fixtures/snippets/distance.adoc index de46eda7b08..5af2a258d68 100644 --- a/tests/golden/fixtures/snippets/distance.adoc +++ b/tests/golden/fixtures/snippets/distance.adoc @@ -24,10 +24,6 @@ distance( This function returns the distance between two points according to the Euclidean distance formula. -=== Return Value - -The distance between the two points - === Parameters [cols="1,4"] @@ -43,5 +39,9 @@ The distance between the two points | The y‐coordinate of the second point |=== +=== Return Value + +The distance between the two points + [.small]#Created with https://www.mrdocs.com[MrDocs]# diff --git a/tests/golden/fixtures/snippets/function_object.adoc b/tests/golden/fixtures/snippets/function_object.adoc index 5894277550a..fdc296680d3 100644 --- a/tests/golden/fixtures/snippets/function_object.adoc +++ b/tests/golden/fixtures/snippets/function_object.adoc @@ -21,10 +21,6 @@ abs(double x) noexcept; This function is defined as an https://en.cppreference.com/cpp/algorithm/ranges#Algorithm_function_objects[Algorithm Function Object (AFO)]. ==== -=== Return Value - -The absolute value of x. - === Parameters [cols="1,4"] @@ -34,5 +30,9 @@ The absolute value of x. | The input value. |=== +=== Return Value + +The absolute value of x. + [.small]#Created with https://www.mrdocs.com[MrDocs]# diff --git a/tests/golden/fixtures/snippets/insert_sorted.adoc b/tests/golden/fixtures/snippets/insert_sorted.adoc index 6c0a5472635..291b9919dc8 100644 --- a/tests/golden/fixtures/snippets/insert_sorted.adoc +++ b/tests/golden/fixtures/snippets/insert_sorted.adoc @@ -18,6 +18,17 @@ insert_sorted( int value); ---- +=== Parameters + +[cols="1,4"] +|=== +| Name| Description +| *v* +| The sorted vector to insert into. +| *value* +| The value to insert. +|=== + === Exceptions [cols="1,4"] @@ -31,17 +42,6 @@ insert_sorted( An iterator to the inserted element. -=== Parameters - -[cols="1,4"] -|=== -| Name| Description -| *v* -| The sorted vector to insert into. -| *value* -| The value to insert. -|=== - === Preconditions * `v` is sorted in ascending order. diff --git a/tests/golden/fixtures/snippets/is_prime.adoc b/tests/golden/fixtures/snippets/is_prime.adoc index 255f792d325..603cfa7213d 100644 --- a/tests/golden/fixtures/snippets/is_prime.adoc +++ b/tests/golden/fixtures/snippets/is_prime.adoc @@ -20,10 +20,6 @@ is_prime(unsigned long long n) noexcept; Linear in n. -=== Return Value - -Whether `n` is prime. - === Parameters [cols="1,4"] @@ -33,5 +29,9 @@ Whether `n` is prime. | The number to test |=== +=== Return Value + +Whether `n` is prime. + [.small]#Created with https://www.mrdocs.com[MrDocs]# diff --git a/tests/golden/fixtures/snippets/landing/sqrt.adoc b/tests/golden/fixtures/snippets/landing/sqrt.adoc index 741fd889680..686b23f9fa1 100644 --- a/tests/golden/fixtures/snippets/landing/sqrt.adoc +++ b/tests/golden/fixtures/snippets/landing/sqrt.adoc @@ -39,14 +39,6 @@ Returns zero for zero input. ==== -=== Return Value - -The integer square root of `value`. - -[NOTE] -==== -The return value https://en.cppreference.com/cpp/language/attributes/nodiscard[should not be discarded^]. -==== === Template Parameters [cols="1,4"] @@ -65,6 +57,14 @@ The return value https://en.cppreference.com/cpp/language/attributes/nodiscard[s | The integral value, which must be non‐negative. |=== +=== Return Value + +The integer square root of `value`. + +[NOTE] +==== +The return value https://en.cppreference.com/cpp/language/attributes/nodiscard[should not be discarded^]. +==== === Preconditions * `value >= 0`. diff --git a/tests/golden/fixtures/snippets/landing/sqrt.html b/tests/golden/fixtures/snippets/landing/sqrt.html index 86e2d48a275..4eade2f7edb 100644 --- a/tests/golden/fixtures/snippets/landing/sqrt.html +++ b/tests/golden/fixtures/snippets/landing/sqrt.html @@ -39,15 +39,6 @@

NOTE

Returns zero for zero input.

-
-

Return Value

-

The integer square root of value.

-
-

NOTE

-
-

The return value should not be discarded.

-
-

Template Parameters

@@ -70,6 +61,15 @@

Parameters

+
+

Return Value

+

The integer square root of value.

+
+

NOTE

+
+

The return value should not be discarded.

+
+

Preconditions