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}}