docs(generators): template partials

Author: alandefreitas

docs/modules/ROOT/pages/generators.adoc

@@ -89,15 +89,17 @@ Each symbol goes through a main layout template in the `<addons>/generator/<gene
 This template is a simple entry point that renders the partial relative to the symbol kind.
 
 The partials are located in the `<addons>/generator/<generator>/partials` directory.
-It contains the following subdirectories:
+It typically contains the following files and subdirectories:
 
-* `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.
+* `symbol`: A generic partial for rendering symbols.
+* `location`: Partials for rendering <<location-fields,location objects>>.
+* `symbol`: Partials for rendering <<symbol-fields,Symbol Objects>>.
+* `template`: Partials for rendering <<template-info-fields,Template Info Objects>>.
+* `type`: Partials for rendering <<type-info-fields,Type Info Objects>>.
 * `markup`: partials for rendering markup elements such as lists, tables, and code blocks, in the output format.
 
+Please refer to the <<dom_reference,Document Object Model Reference>> for more information on each type of object.
+
 Partials common to all generators are available in the `<addons>/generator/common/partials` directory.
 The common partials are loaded before the generator-specific partials, which can override any common partials.
 

share/mrdocs/addons/generator/adoc/layouts/wrapper.adoc.hbs

@@ -1,8 +1,14 @@
 {{! The wrapper for single page documentation or symbols in a multipage documentation }}
-{{#unless @root.config.multipage }}
+{{! Title }}
+{{#if @root.config.multipage }}
+{{! Multipage documentation: symbol is available to the wrapper }}
+[#{{{symbol.anchor}}}]
+= {{> symbol/qualified-name symbol }}
+{{else}}
+{{! Single page documentation: symbol is not available to the wrapper }}
 = Reference
+{{/if}}
 :mrdocs:
-{{/unless}}
 
 {{! Content generated with index.hbs }}
 {{{contents}}}

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

@@ -1,5 +1,9 @@
+{{#unless @root.config.multipage }}
+{{! Single page documentation: symbol is not available to the wrapper but it's available here }}
+{{! Include the symbol title at a higher level }}
 [#{{{symbol.anchor}}}]
-={{#unless @root.config.multipage}}={{/unless}} {{#unless (eq symbol.kind "friend")}}{{#if symbol.name}}{{>types/nested-name-specifier symbol=symbol.parent includeNamespace=true}}{{symbol.name}}{{else}}{{#if symbol.parent}}Unnamed{{else}}Global{{/if}} {{or symbol.tag symbol.kind}}{{/if}}{{else}}{{#if symbol.symbol.name}}{{>types/nested-name-specifier symbol=symbol.symbol.parent includeNamespace=true}}{{symbol.symbol.name}}{{else}}{{symbol.type.name}}{{/if}}{{/unless}}
+== {{> symbol/qualified-name symbol }}
+{{/unless}}
 
 {{! Brief }}
 {{#if symbol.doc.brief}}
@@ -10,20 +14,20 @@
 {{#unless (contains (arr "namespace") symbol.kind)}}
 =={{#unless @root.config.multipage}}={{/unless}} Synopsis
 
-{{>types/source dcl=(primary_location symbol)}}
+{{>location/source dcl=(primary_location symbol)}}
 
 {{#if (ne symbol.kind "overloads")}}
 [source,cpp,subs="verbatim,macros,-callouts"]
 ----
-{{> signature }}
+{{> symbol/signature symbol }}
 
 ----
 
 {{else}}
 {{#each symbol.members as | member |}}
 [source,cpp,subs="verbatim,macros,-callouts"]
 ----
-{{> signature symbol=member link=member}}
+{{> symbol/signature member link=member}}
 
 ----
 
@@ -34,15 +38,15 @@
 {{#if symbol.interface}}
 {{#if (eq symbol.kind "record")}}
 {{#with symbol.interface}}
-{{>types/tranche tranche=public label="" is-namespace=false}}
+{{>symbol/tranche tranche=public label="" is-namespace=false}}
 
-{{>types/tranche tranche=protected label="Protected" is-namespace=false}}
+{{>symbol/tranche tranche=protected label="Protected" is-namespace=false}}
 
-{{>types/tranche tranche=private label="Private" is-namespace=false}}
+{{>symbol/tranche tranche=private label="Private" is-namespace=false}}
 
 {{/with}}
 {{else}}
-{{>types/tranche tranche=symbol.interface label="" is-namespace=true}}
+{{>symbol/tranche tranche=symbol.interface label="" is-namespace=true}}
 
 {{/if}}
 {{else if symbol.members}}
@@ -54,15 +58,15 @@
 |===
 |Name |Description
 {{#each symbol.members}}
-|xref:{{{anchor}}}[`pass:v[{{>types/declarator-id . nolink=true}}]`] | {{~doc.brief}}
+|xref:{{{anchor}}}[`pass:v[{{>symbol/name . nolink=true}}]`] | {{~doc.brief}}
 {{/each}}
 |===
 
 {{/if}}
 {{/if}}
 {{! Using directives }}
 {{#if symbol.usingDirectives}}
-{{>types/info-list members=symbol.usingDirectives title="Using Directives"}}
+{{>symbol/members-table members=symbol.usingDirectives title="Using Directives"}}
 
 {{/if}}
 {{! Description }}
@@ -161,7 +165,7 @@
 =={{#unless @root.config.multipage}}={{/unless}} Parameters
 
 |===
-| Name | Description {{! TODO: | Type? }}
+| Name | Description
 
 {{#each symbol.doc.params}}
 | *{{name}}*
@@ -176,7 +180,7 @@
 =={{#unless @root.config.multipage}}={{/unless}} Parameters
 
 |===
-| Name | Description {{! TODO: | Type? }}
+| Name | Description
 
 {{#each allParams as |param|}}
 | *{{param.name}}*

share/mrdocs/addons/generator/common/partials/location/source.hbs

@@ -0,0 +1,19 @@
+{{!--
+    Renders where the symbol is declared with a link
+
+    If the `base-url` config option is defined, the file name will be
+    linked to the source file.
+
+    Expected Context: {Location Object}
+
+    Example:
+        {{> location/source symbol.loc.def }}
+
+--}}
+Declared in {{#>markup/code~}}
+    {{ str "<" }}{{#unless (and @root.config.base-url (eq dcl.kind "source"))~}}
+        {{dcl.file}}
+    {{~else~}}
+        {{#>markup/a href=(concat @root.config.base-url dcl.file '#L' dcl.line)}}{{dcl.file}}{{/markup/a}}
+    {{~/unless~}}{{ str ">" }}
+{{~/markup/code}}

share/mrdocs/addons/generator/common/partials/signature.hbs

@@ -2,7 +2,7 @@
 {{#>markup/tr~}}
 {{#>markup/td}}
 {{! Member name, linked to its documentation }}
-{{#>markup/a href=(relativize url)}}{{#>markup/code}}{{>types/declarator-id . nolink=true}}{{/markup/code}}{{/markup/a}} {{>types/special-name-suffix .}}
+{{#>markup/a href=(relativize url)}}{{#>markup/code}}{{>symbol/name . nolink=true}}{{/markup/code}}{{/markup/a}} {{>symbol/special-function-suffix .}}
 {{~/markup/td}}
 {{#>markup/td}}
 {{#if (ne kind "overloads")~}}

share/mrdocs/addons/generator/common/partials/signature/alias.hbs

@@ -1,4 +1,16 @@
-{{! List the "members" field of a symbol as a table with the symbol name and brief for each member. }}
+{{!--
+    Renders all symbols of the "members" field as a table.
+
+    This partials renders each row with the symbol name and brief for
+    each member.
+
+    Expected Context: {Symbol Object}
+
+    Example:
+        {{> symbol/members-table symbol }}
+
+    See: https://mrdocs.com/docs/mrdocs/develop/generators.html#dom_reference
+--}}
 {{#if members}}
 {{#>markup/h level=(select @root.config.multipage 1 2)}}{{title}}{{/markup/h}}
 {{#>markup/table cols=2}}
@@ -10,7 +22,7 @@
 {{/markup/thead}}
 {{#>markup/tbody}}
 {{#each (sort_by members "name")}}
-{{>types/info-member .}}
+{{> symbol/detail/members-table-row .}}
 {{/each}}
 {{/markup/tbody}}
 {{/markup/table}}

share/mrdocs/addons/generator/common/partials/signature/concept.hbs

@@ -0,0 +1,33 @@
+{{!--
+    Renders a Name Info object.
+
+    Expected Context: {Name Info Object}
+
+    Optional parameters:
+        nolink: If true, the name will not be linked.
+
+    Example:
+        {{> name-info symbol }}
+
+    See: https://mrdocs.com/docs/mrdocs/develop/generators.html#dom_reference
+--}}
+{{#if prefix~}}
+    {{> symbol/name-info prefix nolink=nolink~}}::
+{{~/if~}}
+{{#if (contains (arr "see-below" "implementation-defined") name)~}}
+    {{! These are special names that should not be linked. }}
+    {{ str '_'}}{{name}}{{ str '_'~}}
+{{else~}}
+    {{! Render the name of the symbol. ~}}
+    {{#if (and symbol.url (not nolink))~}}
+        {{! Link to the symbol's documentation. ~}}
+        {{#>markup/a href=(relativize symbol.url)}}{{name}}{{/markup/a~}}
+    {{else~}}
+        {{! No link, just the name. ~}}
+        {{name~}}
+    {{/if~}}
+    {{#if args~}}
+        {{! Render the template arguments of the symbol. ~}}
+        {{>template/args args=args nolink=nolink~}}
+    {{/if~}}
+{{/if~}}

share/mrdocs/addons/generator/common/partials/signature/enum.hbs

@@ -0,0 +1,36 @@
+{{!--
+    Renders the symbol name in an appropriate format for section titles.
+
+    This is typically a linked name, but it can also be a special name like
+    "see-below" or "implementation-defined".
+
+    Expected Context: {Symbol Object}
+
+    Optional parameters:
+        nolink: If true, types and symbols will not be linked.
+        link: Symbol that should be linked to, regardless of the original symbol.
+
+    Example:
+        {{> declarator symbol }}
+
+    See: https://mrdocs.com/docs/mrdocs/develop/generators.html#dom_reference
+--}}
+{{#if (and (eq kind "function") (eq class "conversion"))~}}
+    {{! Conversion operator: "operator" and the type declarator ~}}
+    operator {{>type/declarator return nolink=nolink~}}
+{{else if (eq kind "guide")~}}
+    {{! Deduction guide: "deduced" type declarator ~}}
+    {{>type/declarator deduced nolink=nolink~}}
+{{else~}}
+    {{#if (and link.url (not nolink))~}}
+        {{! Symbol with URL: link to the symbol documentation ~}}
+        {{#>markup/a href=(relativize link.url)}}{{name}}{{/markup/a~}}
+    {{else~}}
+        {{! Symbol without URL: plain text ~}}
+        {{name~}}
+    {{/if~}}
+    {{#if (contains (arr "explicit" "partial") template.kind)~}}
+        {{! Explicit or partial template: render the template arguments ~}}
+        {{>template/args args=template.args nolink=nolink~}}
+    {{/if~}}
+{{/if}}