fix: manual description comes before member lists

fix #1105

Author: alandefreitas

share/mrdocs/addons/generator/adoc/partials/symbol.adoc.hbs

@@ -28,6 +28,15 @@
 
 {{> symbol/signatures symbol }}
 {{/unless}}
+{{! Description }}
+{{#if symbol.doc.description}}
+{{#unless traversing-global-namespace}}
+{{#unless (eq (lookup (first symbol.doc.description) "kind") "heading") }}
+{{#> markup/dynamic-level-h }}Description{{/markup/dynamic-level-h~}}
+{{~/unless}}
+{{> doc/block/document symbol.doc.description }}
+{{/unless}}
+{{/if}}
 {{! Base classes }}
 {{#if (any_of_by symbol.bases "isPublic")}}
 {{#> markup/dynamic-level-h }}Base Classes{{/markup/dynamic-level-h~}}
@@ -126,15 +135,6 @@
 {{/each}}
 |===
 
-{{/if}}
-{{! Description }}
-{{#if symbol.doc.description}}
-{{#unless traversing-global-namespace}}
-{{#unless (eq (lookup (first symbol.doc.description) "kind") "heading") }}
-{{#> markup/dynamic-level-h }}Description{{/markup/dynamic-level-h~}}
-{{~/unless}}
-{{> doc/block/document symbol.doc.description }}
-{{/unless}}
 {{/if}}
 {{! Using symbols }}
 {{#if symbol.shadows}}
@@ -244,4 +244,4 @@
 {{> symbol symbol=. id=null traversing-global-namespace=true }}
 {{/if}}
 {{/each}}
-{{/if}}
+{{/if}}

share/mrdocs/addons/generator/html/partials/symbol.html.hbs

@@ -38,6 +38,17 @@
 {{> symbol/signatures symbol ~}}
 </div>
 {{/unless}}
+{{! Description }}
+{{#if symbol.doc.description}}
+{{#unless traversing-global-namespace}}
+<div>
+{{#unless (eq (lookup (first symbol.doc.description) "kind") "heading") }}
+{{#> markup/dynamic-level-h level=2 }}Description{{/markup/dynamic-level-h~}}
+{{~/unless}}
+{{> doc/block/document symbol.doc.description }}
+</div>
+{{/unless}}
+{{/if}}
 {{! Base classes }}
 {{#if (any_of_by symbol.bases "isPublic")}}
 <div>
@@ -171,17 +182,6 @@
 </table>
 </div>
 {{/if}}
-{{! Description }}
-{{#if symbol.doc.description}}
-{{#unless traversing-global-namespace}}
-<div>
-{{#unless (eq (lookup (first symbol.doc.description) "kind") "heading") }}
-{{#> markup/dynamic-level-h level=2 }}Description{{/markup/dynamic-level-h~}}
-{{~/unless}}
-{{> doc/block/document symbol.doc.description }}
-</div>
-{{/unless}}
-{{/if}}
 {{! Using symbols }}
 {{#if symbol.shadows}}
 <div>

test-files/golden-tests/config/auto-relates/derived.adoc

@@ -195,6 +195,10 @@ struct AView2
     : link:#AView[AView]
 ----
 
+=== Description
+
+Used to test indirect derived classes
+
 === Base Classes
 
 [cols="1,4"]
@@ -223,10 +227,6 @@ struct AView2
 | A non‐member function of ABase
 |===
 
-=== Description
-
-Used to test indirect derived classes
-
 [#f1]
 == f1
 

test-files/golden-tests/config/auto-relates/derived.html

@@ -248,6 +248,11 @@ <h3>
     : <a href="#AView">AView</a></code></pre>
 </div>
 <div>
+<h3>
+Description</h3>
+<p>Used to test indirect derived classes</p>
+</div>
+<div>
 <h2>
 Base Classes</h2>
 <table>
@@ -283,11 +288,6 @@ <h2>
 </tbody>
 </table>
 </div>
-<div>
-<h3>
-Description</h3>
-<p>Used to test indirect derived classes</p>
-</div>
 </div>
 <div>
 <div>

test-files/golden-tests/filters/symbol-name/extraction-mode.adoc

@@ -99,6 +99,10 @@ Declared in `<extraction‐mode.cpp>`
 struct regular;
 ----
 
+=== Description
+
+The symbol should have a page as usual
+
 === Types
 
 [cols="1,4"]
@@ -118,10 +122,6 @@ struct regular;
 | A function to get a regular symbol
 |===
 
-=== Description
-
-The symbol should have a page as usual
-
 [#regular_ns-regular-also_regular]
 == link:#regular_ns[regular_ns]::link:#regular_ns-regular[regular]::also_regular
 
@@ -272,6 +272,12 @@ A symbol that passes the see‐below filter
 
 A see‐below namespace
 
+=== Description
+
+All member symbols should become see‐below. All members are traversed as see‐below.
+
+The documentation page for these symbols should include the see‐below comment.
+
 === Types
 
 [cols="1,4"]
@@ -294,12 +300,6 @@ A see‐below namespace
 | A function to get an implementation‐defined symbol in a see‐below namespace
 |===
 
-=== Description
-
-All member symbols should become see‐below. All members are traversed as see‐below.
-
-The documentation page for these symbols should include the see‐below comment.
-
 [#see_below_ns-regular]
 == link:#see_below_ns[see_below_ns]::regular
 
@@ -442,6 +442,10 @@ Declared in `<extraction‐mode.cpp>`
 struct regular;
 ----
 
+=== Description
+
+This symbol should have a page as usual.
+
 === Types
 
 [cols="1,4"]
@@ -461,10 +465,6 @@ struct regular;
 | A function to get a regular symbol in the global namespace
 |===
 
-=== Description
-
-This symbol should have a page as usual.
-
 [#regular-also_regular]
 == link:#regular[regular]::also_regular
 

test-files/golden-tests/filters/symbol-name/extraction-mode.html

@@ -134,6 +134,11 @@ <h3>
 Declared in <code>&lt;extraction-mode.cpp&gt;</code></div>
 <pre><code class="source-code cpp">struct regular;</code></pre>
 </div>
+<div>
+<h3>
+Description</h3>
+<p>The symbol should have a page as usual</p>
+</div>
 <h2>
 Types</h2>
 <table style="table-layout: fixed; width: 100%;">
@@ -165,11 +170,6 @@ <h2>
 </tbody>
 </table>
 </div>
-<div>
-<h3>
-Description</h3>
-<p>The symbol should have a page as usual</p>
-</div>
 </div>
 <div>
 <div>
@@ -239,13 +239,13 @@ <h3>
 Declared in <code>&lt;extraction-mode.cpp&gt;</code></div>
 <pre><code class="source-code cpp">struct see_below { /* see-below */ };</code></pre>
 </div>
-
-
 <div>
 <h3>
 Description</h3>
 <p>A symbol that passes the filters and the see-below filter. The symbol should have a page as usual but, because it&#x27;s a scope and not a namespace, the members should not be listed on that page.</p>
 </div>
+
+
 </div>
 <div>
 <div>
@@ -364,6 +364,12 @@ <h2 id="see_below_ns">
 <p>A see-below namespace</p>
 </div>
 </div>
+<div>
+<h3>
+Description</h3>
+<p>All member symbols should become see-below. All members are traversed as see-below.</p>
+<p>The documentation page for these symbols should include the see-below comment.</p>
+</div>
 <h2>
 Types</h2>
 <table style="table-layout: fixed; width: 100%;">
@@ -394,12 +400,6 @@ <h2>
 </tbody>
 </table>
 
-<div>
-<h3>
-Description</h3>
-<p>All member symbols should become see-below. All members are traversed as see-below.</p>
-<p>The documentation page for these symbols should include the see-below comment.</p>
-</div>
 </div>
 <div>
 <div>
@@ -417,13 +417,13 @@ <h3>
 Declared in <code>&lt;extraction-mode.cpp&gt;</code></div>
 <pre><code class="source-code cpp">struct regular { /* see-below */ };</code></pre>
 </div>
-
-
 <div>
 <h3>
 Description</h3>
 <p>The symbol becomes see-below because the whole namespace is see-below.</p>
 </div>
+
+
 </div>
 <div>
 <div>
@@ -441,13 +441,13 @@ <h3>
 Declared in <code>&lt;extraction-mode.cpp&gt;</code></div>
 <pre><code class="source-code cpp">struct see_below { /* see-below */ };</code></pre>
 </div>
-
-
 <div>
 <h3>
 Description</h3>
 <p>The symbol becomes see-below because the whole namespace is see-below and because it&#x27;s explicitly marked as see-below.</p>
 </div>
+
+
 </div>
 <div>
 <div>
@@ -574,6 +574,11 @@ <h3>
 Declared in <code>&lt;extraction-mode.cpp&gt;</code></div>
 <pre><code class="source-code cpp">struct regular;</code></pre>
 </div>
+<div>
+<h3>
+Description</h3>
+<p>This symbol should have a page as usual.</p>
+</div>
 <h2>
 Types</h2>
 <table style="table-layout: fixed; width: 100%;">
@@ -605,11 +610,6 @@ <h2>
 </tbody>
 </table>
 </div>
-<div>
-<h3>
-Description</h3>
-<p>This symbol should have a page as usual.</p>
-</div>
 </div>
 <div>
 <div>
@@ -679,14 +679,14 @@ <h3>
 Declared in <code>&lt;extraction-mode.cpp&gt;</code></div>
 <pre><code class="source-code cpp">struct see_below { /* see-below */ };</code></pre>
 </div>
-
-
 <div>
 <h3>
 Description</h3>
 <p>This symbol should have a page as usual but, because it&#x27;s a scope and not a namespace, the members should not be listed on that page.</p>
 <p>The synopsis should say &quot;See below&quot;.</p>
 </div>
+
+
 </div>
 <div>
 <div>

test-files/golden-tests/javadoc/inline/styled.adoc

@@ -27,6 +27,12 @@ Declared in `<styled.cpp>`
 struct A;
 ----
 
+=== Description
+
+Paragraph with `code`, *bold* text, and _italic_ text.
+
+We can also escape these markers: `, *, and _.
+
 === Member Functions
 
 [cols="1,4"]
@@ -36,12 +42,6 @@ struct A;
 | Compare function
 |===
 
-=== Description
-
-Paragraph with `code`, *bold* text, and _italic_ text.
-
-We can also escape these markers: `, *, and _.
-
 [#A-compare]
 == link:#A[A]::compare
 

test-files/golden-tests/javadoc/inline/styled.html

@@ -43,6 +43,12 @@ <h3>
 Declared in <code>&lt;styled.cpp&gt;</code></div>
 <pre><code class="source-code cpp">struct A;</code></pre>
 </div>
+<div>
+<h3>
+Description</h3>
+<p>Paragraph with <code>code</code>, bold text, and italic text.</p>
+<p>We can also escape these markers: &#x60;, *, and _.</p>
+</div>
 <h2>
 Member Functions</h2>
 <table style="table-layout: fixed; width: 100%;">
@@ -59,12 +65,6 @@ <h2>
 
 
 
-<div>
-<h3>
-Description</h3>
-<p>Paragraph with <code>code</code>, bold text, and italic text.</p>
-<p>We can also escape these markers: &#x60;, *, and _.</p>
-</div>
 </div>
 <div>
 <div>

test-files/golden-tests/javadoc/ref/parent_context.html

@@ -141,13 +141,13 @@ <h3>
 Declared in <code>&lt;parent_context.cpp&gt;</code></div>
 <pre><code class="source-code cpp">struct runtime_checks;</code></pre>
 </div>
-
-
 <div>
 <h3>
 Description</h3>
 <p>See <a href="#boost-openmethod-final_virtual_ptr-04"><code>final_virtual_ptr</code></a></p>
 </div>
+
+
 </div>
 <div>
 <div>