From 3abf208235b1cb77c8533c9e863cf03db501e0bf Mon Sep 17 00:00:00 2001 From: Peter Bacon Darwin Date: Thu, 29 Jun 2017 22:23:27 +0100 Subject: [PATCH] build(aio): update doc-gen templates --- .../templates/api/class.template.html | 6 +- .../templates/api/decorator.template.html | 4 +- .../templates/api/directive.template.html | 5 +- .../templates/api/function.template.html | 15 +++- .../api/includes/class-overview.html | 20 ++--- .../templates/api/includes/export-as.html | 4 +- .../templates/api/includes/inputs.html | 11 --- .../api/includes/interface-overview.html | 8 +- .../templates/api/includes/members.html | 29 ------- .../templates/api/includes/metadata.html | 2 +- .../templates/api/includes/outputs.html | 11 --- .../templates/api/includes/selectors.html | 4 +- .../templates/api/includes/statics.html | 19 ----- .../templates/api/interface.template.html | 3 +- .../templates/api/lib/directiveHelpers.html | 13 ++++ .../templates/api/lib/memberHelpers.html | 42 +++++++++++ .../templates/api/type-alias.template.html | 2 +- .../templates/includes/_class-overview.html | 75 ------------------- 18 files changed, 98 insertions(+), 175 deletions(-) delete mode 100644 aio/tools/transforms/templates/api/includes/inputs.html delete mode 100644 aio/tools/transforms/templates/api/includes/members.html delete mode 100644 aio/tools/transforms/templates/api/includes/outputs.html delete mode 100644 aio/tools/transforms/templates/api/includes/statics.html create mode 100644 aio/tools/transforms/templates/api/lib/directiveHelpers.html create mode 100644 aio/tools/transforms/templates/api/lib/memberHelpers.html delete mode 100644 aio/tools/transforms/templates/includes/_class-overview.html diff --git a/aio/tools/transforms/templates/api/class.template.html b/aio/tools/transforms/templates/api/class.template.html index d78fefe0c8..0cbe9f8742 100644 --- a/aio/tools/transforms/templates/api/class.template.html +++ b/aio/tools/transforms/templates/api/class.template.html @@ -1,14 +1,14 @@ +{% import "lib/memberHelpers.html" as memberHelpers -%} {% import "lib/paramList.html" as params -%} {% extends 'export-base.template.html' -%} {% block details %} - {% include "includes/class-overview.html" %} {% block additional %}{% endblock %} {% include "includes/description.html" %} {% include "includes/annotations.html" %} -{% include "includes/statics.html" %} +{$ memberHelpers.renderMemberDetails(doc.statics, 'static-members', 'static-member', 'Static Members') $} {% include "includes/constructor.html" %} -{% include "includes/members.html" %} +{$ memberHelpers.renderMemberDetails(doc.members, 'instance-members', 'instance-member', 'Members') $} {% endblock %} diff --git a/aio/tools/transforms/templates/api/decorator.template.html b/aio/tools/transforms/templates/api/decorator.template.html index f5e9ac0b39..3cb13dcfbc 100644 --- a/aio/tools/transforms/templates/api/decorator.template.html +++ b/aio/tools/transforms/templates/api/decorator.template.html @@ -1,7 +1,9 @@ +{% import "lib/memberHelpers.html" as memberHelper -%} {% import "lib/paramList.html" as params -%} {% extends 'export-base.template.html' %} {% block details %} + {% include "includes/interface-overview.html" %} {% include "includes/description.html" %} - {% include "includes/metadata.html" %} + {$ memberHelper.renderMemberDetails(doc.members, 'metadata-members', 'metadata-member', 'Metadata Properties') $} {% endblock %} diff --git a/aio/tools/transforms/templates/api/directive.template.html b/aio/tools/transforms/templates/api/directive.template.html index 8405fc6a9e..b07a6ddccc 100644 --- a/aio/tools/transforms/templates/api/directive.template.html +++ b/aio/tools/transforms/templates/api/directive.template.html @@ -1,9 +1,10 @@ +{% import "lib/directiveHelpers.html" as directiveHelper -%} {% import "lib/paramList.html" as params -%} {% extends 'class.template.html' -%} {% block additional -%} {% include "includes/selectors.html" %} - {% include "includes/outputs.html" %} - {% include "includes/inputs.html" %} + {$ directiveHelper.renderBindings(doc.inputs, 'inputs', 'input', 'Inputs') $} + {$ directiveHelper.renderBindings(doc.outputs, 'outputs', 'output', 'Outputs') $} {% include "includes/export-as.html" %} {% endblock %} diff --git a/aio/tools/transforms/templates/api/function.template.html b/aio/tools/transforms/templates/api/function.template.html index 85a7b71e09..fd86241011 100644 --- a/aio/tools/transforms/templates/api/function.template.html +++ b/aio/tools/transforms/templates/api/function.template.html @@ -2,8 +2,21 @@ {% extends 'export-base.template.html' -%} {% block details %} +{% if doc.overloads.length === 1 %} - function {$ doc.name $}{$ params.paramList(doc.parameters) $}: {$ doc.returnType or 'any' $}; + function {$ doc.overloads[0].name $}{$ params.paramList(doc.overloads[0].parameters) $} + {%- if doc.overloads[0].type %}: {$ doc.overloads[0].type | escape $}{% endif %}; {% include "includes/description.html" %} +{% else %} +

Overloads

{% for overload in doc.overloads %} + + function {$ overload.name $}{$ params.paramList(overload.parameters) $} + {%- if overload.type %}: {$ overload.type | escape $}{% endif %}; + +
+ {$ overload.description | trimBlankLines | marked $} +
+{% endfor %} +{% endif %} {% endblock %} \ No newline at end of file diff --git a/aio/tools/transforms/templates/api/includes/class-overview.html b/aio/tools/transforms/templates/api/includes/class-overview.html index 50701159fc..08f50418bd 100644 --- a/aio/tools/transforms/templates/api/includes/class-overview.html +++ b/aio/tools/transforms/templates/api/includes/class-overview.html @@ -1,17 +1,13 @@ -{% macro renderMember(member) %}{% if not member.internal -%} -{$ member.name $}{$ params.paramList(member.parameters) | indent(4, false) | trim() $}{$ params.returnType(member.returnType) $} -{%- endif %}{% endmacro -%} +{% import "lib/memberHelpers.html" as memberHelper -%} -
+

Overview

- {$ doc.docType $} {$ doc.name $}{$ doc.heritage $} { - {%- if doc.statics.length %}{% for member in doc.statics %} - static {$ renderMember(member) $}{% endfor %}{% endif %} - {%- if doc.constructorDoc %} - {$ renderMember(doc.constructorDoc) $}{% endif %} - {%- if doc.members.length %}{% for member in doc.members %} - {$ renderMember(member) $}{% endfor %}{% endif %} + {$ doc.docType $} {$ doc.name $}{$ doc.typeParams | escape $}{$ memberHelper.renderHeritage(doc) $} { + {%- if doc.statics.length %}{% for member in doc.statics %}{% if not member.internal %} + {$ memberHelper.renderMember(member) $}{% endif %}{% endfor %}{% endif %} + {%- if doc.members.length %}{% for member in doc.members %}{% if not member.internal %} + {$ memberHelper.renderMember(member) $}{% endif %}{% endfor %}{% endif %} } -
\ No newline at end of file +
diff --git a/aio/tools/transforms/templates/api/includes/export-as.html b/aio/tools/transforms/templates/api/includes/export-as.html index 995383619e..a3fed860db 100644 --- a/aio/tools/transforms/templates/api/includes/export-as.html +++ b/aio/tools/transforms/templates/api/includes/export-as.html @@ -1,8 +1,8 @@ -{%- if doc.directiveOptions.exportAs %} +{%- if doc.exportAs %}

Exported as

- {$ doc.directiveOptions.exportAs $} + {$ doc.exportAs $}
{% endif %} diff --git a/aio/tools/transforms/templates/api/includes/inputs.html b/aio/tools/transforms/templates/api/includes/inputs.html deleted file mode 100644 index e1c956fbb0..0000000000 --- a/aio/tools/transforms/templates/api/includes/inputs.html +++ /dev/null @@ -1,11 +0,0 @@ -{% if doc.inputs %} -
-

Inputs

- {% for binding, property in doc.inputs %} -
- {$ property.bindingName $} bound to {$ property.memberDoc.classDoc.name $}.{$ property.propertyName $} - {$ property.memberDoc.description | trimBlankLines | marked $} -
- {% endfor %} -
-{% endif %} diff --git a/aio/tools/transforms/templates/api/includes/interface-overview.html b/aio/tools/transforms/templates/api/includes/interface-overview.html index 674ce46655..1652d37fba 100644 --- a/aio/tools/transforms/templates/api/includes/interface-overview.html +++ b/aio/tools/transforms/templates/api/includes/interface-overview.html @@ -1,10 +1,10 @@ +{% import "lib/memberHelpers.html" as memberHelper -%} +

Interface Overview

- interface {$ doc.name $}{$ doc.heritage $} { {% if doc.newMember %} - {$ doc.newMember.name | indent(6, false) | trim $}{$ params.paramList(doc.newMember.parameters) | indent(8, false) | trim $}{$ params.returnType(doc.newMember.returnType) $}{% endif %}{% if doc.callMember %} - {$ doc.callMember.name | indent(6, false) | trim $}{$ params.paramList(doc.callMember.parameters) | indent(8, false) | trim $}{$ params.returnType(doc.callMember.returnType) $}{% endif %}{% if doc.members.length %}{% for member in doc.members %}{% if not member.internal %} - {$ member.name | indent(6, false) | trim $}{$ params.paramList(member.parameters) | indent(8, false) | trim $}{$ params.returnType(member.returnType) $}{% endif %}{% endfor %}{% endif %} + interface {$ doc.name $}{$ doc.typeParams | escape $}{$ memberHelper.renderHeritage(doc) $} { {% if doc.members.length %}{% for member in doc.members %}{% if not member.internal %} + {$ memberHelper.renderMember(member) $}{% endif %}{% endfor %}{% endif %} }
\ No newline at end of file diff --git a/aio/tools/transforms/templates/api/includes/members.html b/aio/tools/transforms/templates/api/includes/members.html deleted file mode 100644 index 7ce487b8bc..0000000000 --- a/aio/tools/transforms/templates/api/includes/members.html +++ /dev/null @@ -1,29 +0,0 @@ -{% if doc.members.length or doc.newMember or doc.callMember %} -
-

Members

- {% if doc.newMember %} -
- - {$ doc.newMember.name $}{$ params.paramList(doc.newMember.parameters) | trim $}{$ params.returnType(doc.newMember.returnType) $} - {% if not doc.newMember.notYetDocumented %}{$ doc.newMember.description | marked $}{% endif %} -
- {% if doc.members.length or doc.callMember %}
{% endif %} - {% endif %} - {% if doc.callMember %} -
- - {$ doc.callMember.name $}{$ params.paramList(doc.callMember.parameters) | trim $}{$ params.returnType(doc.callMember.returnType) $} - {% if not doc.callMember.notYetDocumented %}{$ doc.callMember.description | marked $}{% endif %} -
- {% if doc.members.length %}
{% endif %} - {% endif %} - {% for member in doc.members %}{% if not member.internal %} -
- - {$ member.name $}{$ params.paramList(member.parameters) | trim $}{$ params.returnType(member.returnType) $} - {% if not member.notYetDocumented %}{$ member.description | marked $}{% endif %} -
- {% if not loop.last %}
{% endif %} - {% endif %}{% endfor %} -
-{% endif %} diff --git a/aio/tools/transforms/templates/api/includes/metadata.html b/aio/tools/transforms/templates/api/includes/metadata.html index e632ac5abf..1746529d4f 100644 --- a/aio/tools/transforms/templates/api/includes/metadata.html +++ b/aio/tools/transforms/templates/api/includes/metadata.html @@ -4,7 +4,7 @@ {% for metadata in doc.members %}{% if not metadata.internal %}
- {$ metadata.name $}{$ params.paramList(metadata.parameters) | trim $}{$ params.returnType(metadata.returnType) $} + {$ metadata.name $}{$ params.paramList(metadata.parameters) | trim $}{$ params.returnType(metadata.type) $} {%- if not metadata.notYetDocumented %}{$ metadata.description | marked $}{% endif -%}
{% if not loop.last %}
{% endif %} diff --git a/aio/tools/transforms/templates/api/includes/outputs.html b/aio/tools/transforms/templates/api/includes/outputs.html deleted file mode 100644 index 46a46e532f..0000000000 --- a/aio/tools/transforms/templates/api/includes/outputs.html +++ /dev/null @@ -1,11 +0,0 @@ -{% if doc.outputs %} -
-

Outputs

- {% for binding, property in doc.outputs %} -
- {$ property.bindingName $} bound to {$ property.memberDoc.classDoc.name $}.{$ property.propertyName $} - {$ property.memberDoc.description | trimBlankLines | marked $} -
- {% endfor %} -
-{% endif %} diff --git a/aio/tools/transforms/templates/api/includes/selectors.html b/aio/tools/transforms/templates/api/includes/selectors.html index 393359a6c3..7c42e2566d 100644 --- a/aio/tools/transforms/templates/api/includes/selectors.html +++ b/aio/tools/transforms/templates/api/includes/selectors.html @@ -1,7 +1,7 @@ -{%- if doc.directiveOptions.selector.split(',').length %} +{%- if doc.selector %}

Selectors

- {% for selector in doc.directiveOptions.selector.split(',') %} + {% for selector in doc.selector.split(',') %}
{$ selector $}
diff --git a/aio/tools/transforms/templates/api/includes/statics.html b/aio/tools/transforms/templates/api/includes/statics.html deleted file mode 100644 index 7bdc4576f7..0000000000 --- a/aio/tools/transforms/templates/api/includes/statics.html +++ /dev/null @@ -1,19 +0,0 @@ -{% if doc.statics.length %} -
-

Static Members

- {% for member in doc.statics %}{% if not member.internal %} -
- - {$ member.name $}{$ params.paramList(member.parameters) | trim $}{$ params.returnType(member.returnType) $} - {%- if not member.notYetDocumented %} - {$ member.description | marked $} - {% endif %} -
- - {% if not loop.last %} -
- {% endif %} - - {% endif %}{% endfor %} -
-{% endif %} diff --git a/aio/tools/transforms/templates/api/interface.template.html b/aio/tools/transforms/templates/api/interface.template.html index 728d886a9e..603e8a146a 100644 --- a/aio/tools/transforms/templates/api/interface.template.html +++ b/aio/tools/transforms/templates/api/interface.template.html @@ -1,8 +1,9 @@ {% import "lib/paramList.html" as params -%} +{% import "lib/memberHelpers.html" as memberHelper -%} {% extends 'export-base.template.html' -%} {% block details %} {% include "includes/interface-overview.html" %} {% include "includes/description.html" %} - {% include "includes/members.html" %} + {$ memberHelper.renderMemberDetails(doc.members, 'instance-members', 'instance-member', 'Members') $} {% endblock %} diff --git a/aio/tools/transforms/templates/api/lib/directiveHelpers.html b/aio/tools/transforms/templates/api/lib/directiveHelpers.html new file mode 100644 index 0000000000..937f02b891 --- /dev/null +++ b/aio/tools/transforms/templates/api/lib/directiveHelpers.html @@ -0,0 +1,13 @@ +{% macro renderBindings(bindings, cssContainerClass, cssItemClass, title) -%} +{% if bindings.length %} +
+

{$ title $}

+ {% for binding in bindings %} +
+ {$ binding.bindingName $} bound to {$ binding.memberDoc.containerDoc.name $}.{$ binding.propertyName $} + {#{$ binding.memberDoc.description | trimBlankLines | marked $}#} +
+ {% endfor %} +
+{% endif %} +{%- endmacro %} \ No newline at end of file diff --git a/aio/tools/transforms/templates/api/lib/memberHelpers.html b/aio/tools/transforms/templates/api/lib/memberHelpers.html new file mode 100644 index 0000000000..d180bc1ec3 --- /dev/null +++ b/aio/tools/transforms/templates/api/lib/memberHelpers.html @@ -0,0 +1,42 @@ +{% import "lib/paramList.html" as params -%} + +{%- macro renderHeritage(exportDoc) -%} + {%- if exportDoc.extendsClauses.length %} extends {% for clause in exportDoc.extendsClauses -%} + {$ clause $}{% if not loop.last %}, {% endif -%} + {% endfor %}{% endif %} + {%- if exportDoc.implementsClauses.length %} implements {% for clause in exportDoc.implementsClauses -%} + {$ clause $}{% if not loop.last %}, {% endif -%} + {% endfor %}{% endif %} +{%- endmacro -%} + +{%- macro renderMember(member) -%} + {%- if member.accessibility !== 'public' %}{$ member.accessibility $} {% endif -%} + {%- if member.isGetAccessor %}get {% endif -%} + {%- if member.isSetAccessor %}set {% endif -%} + {%- if member.isStatic %}static {% endif -%} + {$ member.name $}{$ member.typeParameters | escape $}{$ params.paramList(member.parameters) | trim $} + {%- if member.isOptional %}?{% endif -%} + {$ params.returnType(member.type) $} +{%- endmacro -%} + +{%- macro renderMemberDetail(member, cssClass) -%} +
+ + {$ renderMember(member) $} + {%- if not member.notYetDocumented %} + {$ member.description | marked $} + {% endif -%} +
+{% endmacro -%} + +{% macro renderMemberDetails(members, containerClass, itemClass, titleText) %} +{% if members.length %} +
+

{$ titleText $}

+ {% for member in members %}{% if not member.internal %} + {$ renderMemberDetail(member, itemClass) $} + {% if not loop.last %}
{% endif %} + {% endif %}{% endfor %} +
+{% endif %} +{% endmacro %} \ No newline at end of file diff --git a/aio/tools/transforms/templates/api/type-alias.template.html b/aio/tools/transforms/templates/api/type-alias.template.html index d2766eb6d3..05ce96bdb7 100644 --- a/aio/tools/transforms/templates/api/type-alias.template.html +++ b/aio/tools/transforms/templates/api/type-alias.template.html @@ -2,7 +2,7 @@ {% block details %} - type {$ doc.name $} = {$ doc.typeDefinition $}; + type {$ doc.name $}{% if doc.typeDefinition %} = {$ doc.typeDefinition | escape $}{% endif %}; {% include "includes/description.html" %} {% endblock %} diff --git a/aio/tools/transforms/templates/includes/_class-overview.html b/aio/tools/transforms/templates/includes/_class-overview.html deleted file mode 100644 index 580d2279e3..0000000000 --- a/aio/tools/transforms/templates/includes/_class-overview.html +++ /dev/null @@ -1,75 +0,0 @@ -
-

Properties and Methods

-
- - - - - - - - - - - {% if doc.statics.length %} - {% for member in doc.statics %}{% if not member.internal %}> - - - - - {% endif %}{% endfor %} - {% endif %} - - - {% if doc.constructorDoc.name %} - - - - - {% endif %} - - - {% if doc.members.length %} - {% for member in doc.members %}{% if not member.internal %} - - - - - {% endif %}{% endfor %} - {% endif %} - -
{$ doc.name $} Properties
- 
-                {$ member.name $}
-
- 		- 
-                
-                  {$ params.paramList(member.parameters) | indent(8, false) | trim $}{$ params.returnType(member.returnType) $}
-                
-
-
- 
-              {$ doc.constructorDoc.name $}
-
- 		- 
-              {$ params.paramList(member.parameters) | indent(8, false) | trim $}{$ params.returnType(member.returnType) $}
-
-
- 
-                
-                  {$ member.name | indent(6, false) | trim $}
-                
-
- 		- 
-                
-                  {$ params.paramList(member.parameters) | indent(8, false) | trim $}{$ params.returnType(member.returnType) $}
-                
-
-
- -
- -
\ No newline at end of file