Skip to content

feat(generators): document function parameters and template parameters right after the description #1320

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
gennaroprota wants to merge 1 commit into
base: develop
Choose a base branch
from
Open

feat(generators): document function parameters and template parameters right after the description #1320

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions data/mrdocs/addons/generator/common/partials/symbol.hbs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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}}
Expand All @@ -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}}
Expand Down
92 changes: 46 additions & 46 deletions docs/website/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -309,10 +309,6 @@ <h3>Synopsis</h3>
<h3>Description</h3>
<p>This function returns the distance between two points according to the Euclidean distance formula.</p>
</div><!-- /description -->
<div class="return-value">
<h3>Return Value</h3>
<p>The distance between the two points</p>
</div><!-- /return-value -->
<div class="parameters">
<h3>Parameters</h3>
<table style="table-layout: fixed; width: 100%;">
Expand All @@ -327,6 +323,10 @@ <h3>Parameters</h3>
</tbody>
</table>
</div><!-- /parameters -->
<div class="return-value">
<h3>Return Value</h3>
<p>The distance between the two points</p>
</div><!-- /return-value -->
</div><!-- /symbol -->

</div>
Expand Down Expand Up @@ -382,6 +382,18 @@ <h3>Synopsis</h3>
<span class="hljs-type">std</span>::<span class="hljs-type">vector</span>&lt;<span class="hljs-keyword">int</span>&gt;&amp; v,
<span class="hljs-keyword">int</span> value);</code></pre>
</div><!-- /synopsis -->
<div class="parameters">
<h3>Parameters</h3>
<table style="table-layout: fixed; width: 100%;">
<thead>
<tr><th>Name</th><th>Description</th></tr>
</thead>
<tbody>
<tr><td><strong>v</strong></td><td>The sorted vector to insert into.</td></tr>
<tr><td><strong>value</strong></td><td>The value to insert.</td></tr>
</tbody>
</table>
</div><!-- /parameters -->
<div class="exceptions">
<h3>Exceptions</h3>
<table style="table-layout: fixed; width: 100%;">
Expand All @@ -397,18 +409,6 @@ <h3>Exceptions</h3>
<h3>Return Value</h3>
<p>An iterator to the inserted element.</p>
</div><!-- /return-value -->
<div class="parameters">
<h3>Parameters</h3>
<table style="table-layout: fixed; width: 100%;">
<thead>
<tr><th>Name</th><th>Description</th></tr>
</thead>
<tbody>
<tr><td><strong>v</strong></td><td>The sorted vector to insert into.</td></tr>
<tr><td><strong>value</strong></td><td>The value to insert.</td></tr>
</tbody>
</table>
</div><!-- /parameters -->
<div class="preconditions">
<h3>Preconditions</h3>
<ul>
Expand Down Expand Up @@ -482,21 +482,6 @@ <h3>Synopsis</h3>
<h3>Description</h3>
<p>This function calculates the square root of a given integral value using bit manipulation, in \(O(\log value)\) time.</p>
</div><!-- /description -->
<div class="exceptions">
<h3>Exceptions</h3>
<table style="table-layout: fixed; width: 100%;">
<thead>
<tr><th>Name</th><th>Thrown on</th></tr>
</thead>
<tbody>
<tr><td><code>std::invalid_argument</code></td><td>If the input value is negative.</td></tr>
</tbody>
</table>
</div><!-- /exceptions -->
<div class="return-value">
<h3>Return Value</h3>
<p>The square root of the input value.</p>
</div><!-- /return-value -->
<div class="template-parameters">
<h3>Template Parameters</h3>
<table style="table-layout: fixed; width: 100%;">
Expand All @@ -519,6 +504,21 @@ <h3>Parameters</h3>
</tbody>
</table>
</div><!-- /parameters -->
<div class="exceptions">
<h3>Exceptions</h3>
<table style="table-layout: fixed; width: 100%;">
<thead>
<tr><th>Name</th><th>Thrown on</th></tr>
</thead>
<tbody>
<tr><td><code>std::invalid_argument</code></td><td>If the input value is negative.</td></tr>
</tbody>
</table>
</div><!-- /exceptions -->
<div class="return-value">
<h3>Return Value</h3>
<p>The square root of the input value.</p>
</div><!-- /return-value -->
</div><!-- /symbol -->

</div>
Expand Down Expand Up @@ -576,10 +576,6 @@ <h4>NOTE</h4>
<p>This function is defined as an <a href="https://en.cppreference.com/cpp/algorithm/ranges#Algorithm_function_objects">Algorithm Function Object (AFO)</a>.</p>
</div>
</div>
<div class="return-value">
<h3>Return Value</h3>
<p>The absolute value of x.</p>
</div><!-- /return-value -->
<div class="parameters">
<h3>Parameters</h3>
<table style="table-layout: fixed; width: 100%;">
Expand All @@ -591,6 +587,10 @@ <h3>Parameters</h3>
</tbody>
</table>
</div><!-- /parameters -->
<div class="return-value">
<h3>Return Value</h3>
<p>The absolute value of x.</p>
</div><!-- /return-value -->
</div><!-- /symbol -->

</div>
Expand Down Expand Up @@ -675,6 +675,17 @@ <h3>Synopsis</h3>
<h3>Description</h3>
<p>The lock is held until the returned object is destroyed.</p>
</div><!-- /description -->
<div class="parameters">
<h3>Parameters</h3>
<table style="table-layout: fixed; width: 100%;">
<thead>
<tr><th>Name</th><th>Description</th></tr>
</thead>
<tbody>
<tr><td><strong>path</strong></td><td>The path of the file to lock.</td></tr>
</tbody>
</table>
</div><!-- /parameters -->
<div class="exceptions">
<h3>Exceptions</h3>
<table style="table-layout: fixed; width: 100%;">
Expand All @@ -695,17 +706,6 @@ <h4>NOTE</h4>
<p>The return value <a href="https://en.cppreference.com/cpp/language/attributes/nodiscard" target="_blank" rel="noopener">should not be discarded</a>.</p>
</div>
</div></div><!-- /return-value -->
<div class="parameters">
<h3>Parameters</h3>
<table style="table-layout: fixed; width: 100%;">
<thead>
<tr><th>Name</th><th>Description</th></tr>
</thead>
<tbody>
<tr><td><strong>path</strong></td><td>The path of the file to lock.</td></tr>
</tbody>
</table>
</div><!-- /parameters -->
</div><!-- /symbol -->

</div>
Expand Down
8 changes: 4 additions & 4 deletions examples/extensions/ghostwriter/reference.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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&hyphen;with&hyphen;tolerance check&period;

=== Return Value

The straight&hyphen;line distance between `a` and `b`&period;

=== Parameters

[cols="1,4"]
Expand All @@ -210,5 +206,9 @@ The straight&hyphen;line distance between `a` and `b`&period;
| The second point&period;
|===

=== Return Value

The straight&hyphen;line distance between `a` and `b`&period;


[.small]#Created with https://www.mrdocs.com[MrDocs]#
8 changes: 4 additions & 4 deletions tests/golden/fixtures/generator/hbs/macros/macros.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,10 +48,6 @@ Declared in `&lt;macros&period;cpp&gt;`

----

=== Return Value

`x` clamped to the range&period;

=== Parameters

[cols="1,4"]
Expand All @@ -65,6 +61,10 @@ Declared in `&lt;macros&period;cpp&gt;`
| The upper bound&period;
|===

=== Return Value

`x` clamped to the range&period;

[#EXAMPLE_LOG]
== EXAMPLE&lowbar;LOG

Expand Down
8 changes: 4 additions & 4 deletions tests/golden/fixtures/generator/hbs/macros/macros.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,10 +48,6 @@ <h3>Synopsis</h3>
<pre><code class="source-code cpp">#define EXAMPLE_CLAMP(x, lo, hi)
</code></pre>
</div><!-- /synopsis -->
<div class="return-value">
<h3>Return Value</h3>
<p><code>x</code> clamped to the range.</p>
</div><!-- /return-value -->
<div class="parameters">
<h3>Parameters</h3>
<table style="table-layout: fixed; width: 100%;">
Expand All @@ -65,6 +61,10 @@ <h3>Parameters</h3>
</tbody>
</table>
</div><!-- /parameters -->
<div class="return-value">
<h3>Return Value</h3>
<p><code>x</code> clamped to the range.</p>
</div><!-- /return-value -->
</div><!-- /symbol -->
<div class="symbol">
<div class="header">
Expand Down
8 changes: 4 additions & 4 deletions tests/golden/fixtures/generator/hbs/noexcept-see-below-limit/noexcept-limit.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,10 +32,6 @@ swap(
T& b) noexcept(&sol;&ast; see-below &ast;&sol;);
----

=== Exception specification

This function is potentially-throwing unless `sizeof(T) &gt; sizeof(int)`.

=== Parameters

[cols="1,4"]
Expand All @@ -47,5 +43,9 @@ This function is potentially-throwing unless `sizeof(T) &gt; sizeof(int)`.
| second value
|===

=== Exception specification

This function is potentially-throwing unless `sizeof(T) &gt; sizeof(int)`.


[.small]#Created with https://www.mrdocs.com[MrDocs]#
8 changes: 4 additions & 4 deletions tests/golden/fixtures/generator/hbs/noexcept-see-below-limit/noexcept-limit.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,10 +36,6 @@ <h3>Synopsis</h3>
T& a,
T& b) noexcept(/* see-below */);</code></pre>
</div><!-- /synopsis -->
<div class="noexcept-specification">
<h3>Exception specification</h3>
<p>This function is potentially-throwing unless <code>sizeof(T) &gt; sizeof(int)</code>.</p>
</div><!-- /noexcept-specification -->
<div class="parameters">
<h3>Parameters</h3>
<table style="table-layout: fixed; width: 100%;">
Expand All @@ -52,6 +48,10 @@ <h3>Parameters</h3>
</tbody>
</table>
</div><!-- /parameters -->
<div class="noexcept-specification">
<h3>Exception specification</h3>
<p>This function is potentially-throwing unless <code>sizeof(T) &gt; sizeof(int)</code>.</p>
</div><!-- /noexcept-specification -->
</div><!-- /symbol -->

</div>
Expand Down
16 changes: 8 additions & 8 deletions tests/golden/fixtures/snippets/commands/copydoc.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,10 +18,6 @@ b64&lowbar;encode(
unsigned int n);
----

=== Return Value

A null&hyphen;terminated base&hyphen;64 string&period; Owned by the caller&period;

=== Parameters

[cols="1,4"]
Expand All @@ -33,6 +29,10 @@ A null&hyphen;terminated base&hyphen;64 string&period; Owned by the caller&perio
| Number of bytes in `data`&period;
|===

=== Return Value

A null&hyphen;terminated base&hyphen;64 string&period; Owned by the caller&period;

[#base64]
== base64

Expand All @@ -50,10 +50,6 @@ base64(
unsigned int n);
----

=== Return Value

A null&hyphen;terminated base&hyphen;64 string&period; Owned by the caller&period;

=== Parameters

[cols="1,4"]
Expand All @@ -65,5 +61,9 @@ A null&hyphen;terminated base&hyphen;64 string&period; Owned by the caller&perio
| Number of bytes in `data`&period;
|===

=== Return Value

A null&hyphen;terminated base&hyphen;64 string&period; Owned by the caller&period;


[.small]#Created with https://www.mrdocs.com[MrDocs]#
8 changes: 4 additions & 4 deletions tests/golden/fixtures/snippets/commands/regex.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,10 +34,6 @@ Declared in `&lt;regex&period;cpp&gt;`
bytecode(link:#regex[regex] const& re);
----

=== Return Value

The bytecode, in an implementation&hyphen;defined form&period;

=== Parameters

[cols="1,4"]
Expand All @@ -47,6 +43,10 @@ The bytecode, in an implementation&hyphen;defined form&period;
| A compiled regular expression&period;
|===

=== Return Value

The bytecode, in an implementation&hyphen;defined form&period;

[#compile]
== compile

Expand Down
8 changes: 4 additions & 4 deletions tests/golden/fixtures/snippets/commands/resample.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,10 +21,6 @@ resample(
Sample* out);
----

=== Return Value

The number of samples written to `out`&period;

=== Template Parameters

[cols="1,4"]
Expand All @@ -49,5 +45,9 @@ The number of samples written to `out`&period;
| Buffer that receives the resampled signal&period;
|===

=== Return Value

The number of samples written to `out`&period;


[.small]#Created with https://www.mrdocs.com[MrDocs]#
8 changes: 4 additions & 4 deletions tests/golden/fixtures/snippets/commands/template-parameters.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,10 +19,6 @@ max&lowbar;of(
T const& b);
----

=== Return Value

the larger of two values&period;

=== Template Parameters

[cols="1,4"]
Expand All @@ -32,5 +28,9 @@ the larger of two values&period;
| A type that supports `operator&lt;`&period;
|===

=== Return Value

the larger of two values&period;


[.small]#Created with https://www.mrdocs.com[MrDocs]#
Loading
Loading