refactor: synchronize HTML templates

docs/modules/ROOT/pages/generators.adoc

@@ -47,19 +47,28 @@ The templates used to generate the documentation are located in the `share/mrdoc
 addons: /path/to/custom/addons
 ----
 
-Each symbol goes through a main layout template in the `share/mrdocs/addons/generator/<generator>/layouts` directory. The multipage generator renders the layout as separate pages for each symbol. The single-page generator renders and concatenates the layout.
+Each symbol goes through a main layout template in the `share/mrdocs/addons/generator/<generator>/layouts/single-symbol.<generator>.hbs` directory. This template is a simple entry point that renders the partial relative to the symbol kind.
 
-Each time the generator encounters a symbol, it renders the layout template with the symbol data as the Handlebars context. The layout template can include other partial templates to render the symbol data. These partials are available in the `share/mrdocs/addons/generator/<generator>/partials` directory.
+The partials are located in the `share/mrdocs/addons/generator/<generator>/partials` directory. It contains the following subdirectories:
 
-The Document Object Model (DOM) for each symbol includes all information about the symbol. One advantage of custom templates over post-processing XML files is the ability to access symbols as a graph. If symbol `A` refers to symbol `B`, some properties of symbol `B` are likely to be required in the documentation of `A`. All templates and generators can access a reference to `B` by searching the symbol tree or simply by accessing the elements `A` refers to. All references to other symbols are resolved in the templates.
+* `symbols`: Contains one partial for each symbol kind. The fields of each symbol object are described in the <<symbol-fields,Symbol Object>> section.
+* `signature`: Contains one partial for each symbol kind that renders the signature of the symbol as if declared in {cpp}.
+* `types`: partials for rendering other types of objects in a canonical form. Please refer to the <<dom_reference,Document Object Model Reference>> for more information on each type of object.
 
+The multipage generator renders the layout multiple times as separate pages for each symbol. The single-page generator renders the layout multiple times and concatenates the results in a single page.
+
+Each time the generator encounters a symbol, it renders the layout template with the symbol data as the Handlebars context.The layout template can include other partial templates to render the symbol data.These partials are available in the `share/mrdocs/addons/generator/<generator>/partials` directory.
+
+The Document Object Model (DOM) for each symbol includes all information about the symbol.One advantage of custom templates over post-processing XML files is the ability to access symbols as a graph.If symbol `A` refers to symbol `B`, some properties of symbol `B` are likely to be required in the documentation of `A`.All templates and generators can access a reference to `B` by searching the symbol tree or simply by accessing the elements `A` refers to.All references to other symbols are resolved in the templates.
+
+[#dom_reference]
 == Document Object Model Reference
 
-The Document Object Model (DOM) is a tree structure that represents the symbols extracted from the source code. The DOM is used by the generator to render the documentation.
+The Document Object Model (DOM) is a tree structure that represents the symbols extracted from the source code.The DOM is used by the generator to render the documentation.
 
 === Top-Level Fields
 
-The top-level object in the DOM is the context for a template. The top-level object has the following properties:
+The top-level object in the DOM is the context for a template.The top-level object has the following properties:
 
 |===
 |Property |Type| Description

share/mrdocs/addons/generator/asciidoc/layouts/overload-set.adoc.hbs

@@ -1,7 +1,8 @@
+{{! A page when the symbol type is "overloads" }}
 {{#if relfileprefix}}:relfileprefix: {{relfileprefix}}{{/if}}
 [#{{sectionref}}]
 
-={{#unless is_multipage}}={{/unless}} {{#if symbol.name}}{{>nested-name-specifier symbol=symbol.parent includeNamespace=true}}{{symbol.name}}{{else}}Unnamed overload set{{/if}}
+={{#unless is_multipage}}={{/unless}} {{#if symbol.name}}{{>types/nested-name-specifier symbol=symbol.parent includeNamespace=true}}{{symbol.name}}{{else}}Unnamed overload set{{/if}}
 
 {{#if symbol.members.[0]}}
 

share/mrdocs/addons/generator/asciidoc/layouts/single-footer.adoc.hbs

@@ -1,2 +1,3 @@
+{{! The footer for single page documentation }}
 
 Created with MrDocs

share/mrdocs/addons/generator/asciidoc/layouts/single-header.adoc.hbs

@@ -1,2 +1,3 @@
+{{! The header for single page documentation }}
 = Reference
 :mrdocs:

share/mrdocs/addons/generator/asciidoc/layouts/single-symbol.adoc.hbs

@@ -1,3 +1,4 @@
+{{! The section with a symbol in single page output or the symbol page in multi page output }}
 {{#if relfileprefix}}:relfileprefix: {{relfileprefix}}{{/if}}
 [#{{sectionref}}]
 

share/mrdocs/addons/generator/asciidoc/partials/signature/alias.adoc.hbs

@@ -1 +1 @@
-namespace {{symbol.name}} = {{>name-info symbol.aliasedSymbol}}
+namespace {{symbol.name}} = {{>types/name-info symbol.aliasedSymbol}}

share/mrdocs/addons/generator/asciidoc/partials/signature/concept.adoc.hbs

@@ -1,3 +1,3 @@
-{{>template-head symbol.template}}
+{{>types/template-head symbol.template}}
 
-concept {{>declarator-id symbol}} = {{symbol.constraint}}
+concept {{>types/declarator-id symbol}} = {{symbol.constraint}}

share/mrdocs/addons/generator/asciidoc/partials/signature/enum.adoc.hbs

@@ -1,2 +1,2 @@
-enum {{>declarator-id symbol~}}
-{{#if symbol.type}} : {{>declarator symbol.type}}{{/if}}
+enum {{>types/declarator-id symbol~}}
+{{#if symbol.type}} : {{>types/declarator symbol.type}}{{/if}}

share/mrdocs/addons/generator/asciidoc/partials/signature/field.adoc.hbs

@@ -1,6 +1,6 @@
 {{#if symbol.isMutable}}mutable
 {{/if~}}
-{{>declarator-before symbol.type}} {{>declarator-id symbol~}}
+{{>types/declarator-before symbol.type}} {{>types/declarator-id symbol~}}
 {{#if symbol.isBitfield}} : {{symbol.bitfieldWidth}}{{/if~}}
 {{#if symbol.default}} = {{symbol.default}}{{/if~}}
-{{>declarator-after symbol.type}}
+{{>types/declarator-after symbol.type}}

share/mrdocs/addons/generator/asciidoc/partials/signature/friend.adoc.hbs

@@ -1,5 +1,5 @@
 {{#if symbol.type~}}
-friend {{>declarator symbol.type~}}
+friend {{>types/declarator symbol.type~}}
 {{else if symbol.symbol~}}
 {{> (concat 'signature' '/' (lookup . 'symbol.symbol.kind')) symbol=symbol.symbol isFriend=true~}}
 {{/if}}

share/mrdocs/addons/generator/asciidoc/partials/signature/function.adoc.hbs

@@ -1,4 +1,4 @@
-{{#if symbol.template}}{{>template-head symbol.template}}
+{{#if symbol.template}}{{>types/template-head symbol.template}}
 {{/if~}}
 {{#if isFriend}}friend
 {{/if~}}
@@ -10,19 +10,19 @@
 {{/if~}}
 {{#if symbol.explicitSpec}}{{symbol.explicitSpec}}
 {{/if~}}
-{{#if (eq symbol.class "normal")}}{{>declarator-before symbol.return}}
+{{#if (eq symbol.class "normal")}}{{>types/declarator-before symbol.return}}
 {{/if~}}
-{{>declarator-id symbol link=(select link link symbol.template.primary)}}
+{{>types/declarator-id symbol link=(select link link symbol.template.primary)}}
 ({{#if symbol.isExplicitObjectMemberFunction}}this {{/if}}{{#each symbol.params}}{{#unless (and @first @last)}}
-    {{/unless}}{{>declarator type decl-name=name~}}
+    {{/unless}}{{>types/declarator type decl-name=name~}}
     {{#if default}} = {{default}}{{/if~}}
     {{#unless @last}},{{/unless~}}
 {{/each~}}{{#if symbol.isVariadic}}{{#if symbol.params}}, {{/if}}...{{/if}})
 {{~#if symbol.isConst}} const{{/if~}}
 {{#if symbol.isVolatile}} volatile{{/if~}}
 {{#if symbol.refQualifier}} {{symbol.refQualifier}}{{/if~}}
 {{#if symbol.exceptionSpec}} {{symbol.exceptionSpec}}{{/if~}}
-{{#if (eq symbol.class "normal")}}{{>declarator-after symbol.return}}{{/if~}}
+{{#if (eq symbol.class "normal")}}{{>types/declarator-after symbol.return}}{{/if~}}
 {{#if symbol.requires}} requires {{symbol.requires}}{{/if~}}
 {{#if symbol.hasOverrideAttr}} override{{/if~}}
 {{#if symbol.isFinal}} final{{/if~}}

share/mrdocs/addons/generator/asciidoc/partials/signature/guide.adoc.hbs

@@ -1,8 +1,8 @@
-{{#if symbol.template}}{{>template-head symbol.template}}
+{{#if symbol.template}}{{>types/template-head symbol.template}}
 {{/if~}}
-{{>declarator-id symbol}}
+{{>types/declarator-id symbol}}
 ({{#each symbol.params}}{{#unless (and @first @last)}}
-    {{/unless}}{{>declarator type decl-name=name~}}
+    {{/unless}}{{>types/declarator type decl-name=name~}}
     {{#if default}} = {{default}}{{/if~}}
     {{#unless @last}},{{/unless~}}
-{{/each~}}) -> {{>declarator symbol.deduced}}
+{{/each~}}) -> {{>types/declarator symbol.deduced}}

share/mrdocs/addons/generator/asciidoc/partials/signature/record.adoc.hbs

@@ -1,6 +1,6 @@
-{{#if symbol.template}}{{>template-head symbol.template}}
+{{#if symbol.template}}{{>types/template-head symbol.template}}
 {{/if~}}
-{{#if isFriend}}friend {{/if}}{{symbol.tag}} {{>declarator-id symbol link=(select link link symbol.template.primary)~}}
+{{#if isFriend}}friend {{/if}}{{symbol.tag}} {{>types/declarator-id symbol link=(select link link symbol.template.primary)~}}
 {{#unless symbol.bases~}}
 {{else if isFriend~}}
 {{else}}
@@ -10,6 +10,6 @@
     :{{else}}
     ,{{/if~}}
     {{#unless (eq access ../symbol.defaultAccess)}} {{access}}{{/unless~}}
-    {{#if isVirtual}} virtual{{/if}} {{>declarator type~}}
+    {{#if isVirtual}} virtual{{/if}} {{>types/declarator type~}}
 {{/each~}}
 {{/unless}}

share/mrdocs/addons/generator/asciidoc/partials/signature/typedef.adoc.hbs

@@ -1,7 +1,7 @@
 {{#if symbol.isUsing~}}
-    {{#if symbol.template}}{{>template-head symbol.template}}
+    {{#if symbol.template}}{{>types/template-head symbol.template}}
     {{/if~}}
-    using {{symbol.name}} = {{>declarator symbol.type}}
+    using {{symbol.name}} = {{>types/declarator symbol.type}}
 {{~else~}}
-    typedef {{>declarator symbol.type decl-name=symbol.name}}
+    typedef {{>types/declarator symbol.type decl-name=symbol.name}}
 {{~/if}}

share/mrdocs/addons/generator/asciidoc/partials/signature/using.adoc.hbs

@@ -1 +1 @@
-using {{#if (eq symbol.class "typename")}}typename {{/if}}{{#if (eq symbol.class "enum")}}enum {{/if}}{{#if symbol.qualifier}}{{>name-info symbol.qualifier}}::{{/if}}{{symbol.name~}}
+using {{#if (eq symbol.class "typename")}}typename {{/if}}{{#if (eq symbol.class "enum")}}enum {{/if}}{{#if symbol.qualifier}}{{>types/name-info symbol.qualifier}}::{{/if}}{{symbol.name~}}

share/mrdocs/addons/generator/asciidoc/partials/signature/variable.adoc.hbs

@@ -1,11 +1,11 @@
-{{#if symbol.template}}{{>template-head symbol.template}}
+{{#if symbol.template}}{{>types/template-head symbol.template}}
 {{/if~}}
 {{#if symbol.constexprKind}}{{symbol.constexprKind}}
 {{/if~}}
 {{#if symbol.storageClass}}{{symbol.storageClass}}
 {{/if~}}
 {{#if symbol.isThreadLocal}}thread_local
 {{/if~}}
-{{>declarator-before symbol.type}} {{>declarator-id symbol link=(select link link symbol.template.primary)~}}
-{{>declarator-after symbol.type~}}
+{{>types/declarator-before symbol.type}} {{>types/declarator-id symbol link=(select link link symbol.template.primary)~}}
+{{>types/declarator-after symbol.type~}}
 {{#if symbol.initializer}} = {{symbol.initializer}}{{/if}}

share/mrdocs/addons/generator/asciidoc/partials/symbols/alias.adoc.hbs

@@ -1,11 +1,11 @@
 {{!-- alias --}}
-={{#unless is_multipage}}={{/unless}} {{>nested-name-specifier symbol=symbol.parent includeNamespace=true}}{{symbol.name}}
+={{#unless is_multipage}}={{/unless}} {{>types/nested-name-specifier symbol=symbol.parent includeNamespace=true}}{{symbol.name}}
 
 {{symbol.doc.brief}}
 
 =={{#unless is_multipage}}={{/unless}} Synopsis
 
-{{>source dcl=(primary_location symbol)}}
+{{>types/source dcl=(primary_location symbol)}}
 
 [source,cpp,subs="verbatim,macros,-callouts"]
 ----

share/mrdocs/addons/generator/asciidoc/partials/symbols/concept.adoc.hbs

@@ -1,11 +1,11 @@
 {{!-- concept --}}
-= {{>nested-name-specifier symbol=symbol.parent includeNamespace=true}}{{symbol.name}}
+= {{>types/nested-name-specifier symbol=symbol.parent includeNamespace=true}}{{symbol.name}}
 
 {{symbol.doc.brief}}
 
 == Synopsis
 
-{{>source dcl=(primary_location symbol)}}
+{{>types/source dcl=(primary_location symbol)}}
 
 [source,cpp,subs="verbatim,macros,-callouts"]
 ----

share/mrdocs/addons/generator/asciidoc/partials/symbols/enum.adoc.hbs

@@ -1,11 +1,11 @@
 {{!-- enum --}}
-={{#unless is_multipage}}={{/unless}} {{#if symbol.name}}{{>nested-name-specifier symbol=symbol.parent includeNamespace=true}}{{symbol.name}}{{else}}Unnamed enum{{/if}}
+={{#unless is_multipage}}={{/unless}} {{#if symbol.name}}{{>types/nested-name-specifier symbol=symbol.parent includeNamespace=true}}{{symbol.name}}{{else}}Unnamed enum{{/if}}
 
 {{symbol.doc.brief}}
 
 =={{#unless is_multipage}}={{/unless}} Synopsis
 
-{{>source dcl=(primary_location symbol)}}
+{{>types/source dcl=(primary_location symbol)}}
 
 [source,cpp,subs="verbatim,macros,-callouts"]
 ----
@@ -18,7 +18,7 @@
 |===
 |Name |Description
 {{#each symbol.members}}
-|xref:{{ref}}[`pass:v[{{>declarator-id . nolink=true}}]`] | {{~doc.brief}}
+|xref:{{ref}}[`pass:v[{{>types/declarator-id . nolink=true}}]`] | {{~doc.brief}}
 {{/each}}
 |===
 {{/if}}

share/mrdocs/addons/generator/asciidoc/partials/symbols/enumerator.adoc.hbs

@@ -1,11 +1,11 @@
 {{!-- enumerator --}}
-={{#unless is_multipage}}={{/unless}} {{>nested-name-specifier symbol=symbol.parent includeNamespace=true}}{{symbol.name}}
+={{#unless is_multipage}}={{/unless}} {{>types/nested-name-specifier symbol=symbol.parent includeNamespace=true}}{{symbol.name}}
 
 {{symbol.doc.brief}}
 
 =={{#unless is_multipage}}={{/unless}} Synopsis
 
-{{>source dcl=(primary_location symbol)}}
+{{>types/source dcl=(primary_location symbol)}}
 
 [source,cpp,subs="verbatim,macros,-callouts"]
 ----

share/mrdocs/addons/generator/asciidoc/partials/symbols/field.adoc.hbs

@@ -1,11 +1,11 @@
 {{!-- field --}}
-={{#unless is_multipage}}={{/unless}} {{>nested-name-specifier symbol=symbol.parent includeNamespace=true}}{{symbol.name}}
+={{#unless is_multipage}}={{/unless}} {{>types/nested-name-specifier symbol=symbol.parent includeNamespace=true}}{{symbol.name}}
 
 {{symbol.doc.brief}}
 
 =={{#unless is_multipage}}={{/unless}} Synopsis
 
-{{>source dcl=(primary_location symbol)}}
+{{>types/source dcl=(primary_location symbol)}}
 
 [source,cpp,subs="verbatim,macros,-callouts"]
 ----

share/mrdocs/addons/generator/asciidoc/partials/symbols/friend.adoc.hbs

@@ -1,11 +1,11 @@
 {{!-- friend --}}
-={{#unless is_multipage}}={{/unless}} {{#if symbol.symbol}}{{>nested-name-specifier symbol=symbol.symbol.parent includeNamespace=true}}{{symbol.symbol.name}}{{else}}{{symbol.type.name}}{{/if}}
+={{#unless is_multipage}}={{/unless}} {{#if symbol.symbol}}{{>types/nested-name-specifier symbol=symbol.symbol.parent includeNamespace=true}}{{symbol.symbol.name}}{{else}}{{symbol.type.name}}{{/if}}
 
 {{symbol.doc.brief}}
 
 =={{#unless is_multipage}}={{/unless}} Synopsis
 
-{{>source dcl=(primary_location symbol)}}
+{{>types/source dcl=(primary_location symbol)}}
 
 [source,cpp,subs="verbatim,macros,-callouts"]
 ----

share/mrdocs/addons/generator/asciidoc/partials/symbols/function.adoc.hbs

@@ -1,11 +1,11 @@
 {{!-- function --}}
-={{#unless is_multipage}}={{/unless}} {{>nested-name-specifier symbol=symbol.parent includeNamespace=true}}{{symbol.name}}
+={{#unless is_multipage}}={{/unless}} {{>types/nested-name-specifier symbol=symbol.parent includeNamespace=true}}{{symbol.name}}
 
 {{symbol.doc.brief}}
 
 =={{#unless is_multipage}}={{/unless}} Synopsis
 
-{{>source dcl=(primary_location symbol)}}
+{{>types/source dcl=(primary_location symbol)}}
 
 [source,cpp,subs="verbatim,macros,-callouts"]
 ----

share/mrdocs/addons/generator/asciidoc/partials/symbols/guide.adoc.hbs

@@ -1,11 +1,11 @@
 {{!-- guides --}}
-={{#unless is_multipage}}={{/unless}} {{>nested-name-specifier symbol=symbol.parent includeNamespace=true}}{{symbol.name}}
+={{#unless is_multipage}}={{/unless}} {{>types/nested-name-specifier symbol=symbol.parent includeNamespace=true}}{{symbol.name}}
 
 {{symbol.doc.brief}}
 
 =={{#unless is_multipage}}={{/unless}} Synopsis
 
-{{>source dcl=(primary_location symbol)}}
+{{>types/source dcl=(primary_location symbol)}}
 
 [source,cpp,subs="verbatim,macros,-callouts"]
 ----

share/mrdocs/addons/generator/asciidoc/partials/symbols/namespace.adoc.hbs

@@ -1,6 +1,6 @@
 {{!-- namespace --}}
-={{#unless is_multipage}}={{/unless}} {{#if symbol.name}}{{>nested-name-specifier symbol=symbol.parent includeNamespace=true}}{{symbol.name}}{{else if symbol.parent}}Unnamed namespace{{else}}Global namespace{{/if}}
+={{#unless is_multipage}}={{/unless}} {{#if symbol.name}}{{>types/nested-name-specifier symbol=symbol.parent includeNamespace=true}}{{symbol.name}}{{else if symbol.parent}}Unnamed namespace{{else}}Global namespace{{/if}}
 
-{{> tranche tranche=symbol.interface label="" is-namespace=true}}
+{{>types/tranche tranche=symbol.interface label="" is-namespace=true}}
 
-{{>info-list members=symbol.usingDirectives title="Using Directives"}}
+{{>types/info-list members=symbol.usingDirectives title="Using Directives"}}