cargdev/angular
1
0
Fork 0
Code Issues 12 Pull Requests Actions Packages Projects Releases Wiki Activity

feat(aio): first pass API docs redesign (#21874)

Browse Source 
Includes:

* display ToC for API docs
* update dgeni-packages to 0.24.1
* add floating sidebar in API docs
* add breadcrumbs and structured data for Google crawler
* improved rendering of method overloads
* properties rendered in a table
* params rendered with docs
* removal of outdated "infobox" from all API docs

PR Close #21874
This commit is contained in:
Pete Bacon Darwin
2018-02-08 15:00:53 +00:00
committed by Miško Hevery
parent bc1e22922a
commit 7007f51c35
33 changed files with 831 additions and 134 deletions
Download Patch File Download Diff File Expand all files Collapse all files

11
aio/tools/transforms/angular-api-package/index.js vendored
View File

@ -21,7 +21,9 @@ module.exports = new Package('angular-api', [basePackage, typeScriptPackage])
.processor(require('./processors/extractDecoratedClasses'))
.processor(require('./processors/matchUpDirectiveDecorators'))
.processor(require('./processors/addMetadataAliases'))
.processor(require('./processors/computeApiBreadCrumbs'))
.processor(require('./processors/filterContainedDocs'))
.processor(require('./processors/processClassLikeMembers'))
.processor(require('./processors/markBarredODocsAsPrivate'))
.processor(require('./processors/filterPrivateDocs'))
.processor(require('./processors/computeSearchTitle'))
@ -86,15 +88,6 @@ module.exports = new Package('angular-api', [basePackage, typeScriptPackage])
// Load up all the tag definitions in the tag-defs folder
parseTagsProcessor.tagDefinitions =
parseTagsProcessor.tagDefinitions.concat(getInjectables(requireFolder(__dirname, './tag-defs')));
// We actually don't want to parse param docs in this package as we are getting the data out using TS
// TODO: rewire the param docs to the params extracted from TS
parseTagsProcessor.tagDefinitions.forEach(function(tagDef) {
if (tagDef.name === 'param') {
tagDef.docProperty = 'paramData';
tagDef.transforms = [];
}
});
})

19
aio/tools/transforms/angular-api-package/processors/computeApiBreadCrumbs.js vendored Normal file
View File

@ -0,0 +1,19 @@
module.exports = function computeApiBreadCrumbs(EXPORT_DOC_TYPES) {
return {
$runAfter: ['paths-computed'],
$runBefore: ['rendering-docs'],
$process(docs) {
// Compute the breadcrumb for each doc by processing its containers
docs.forEach(doc => {
if (EXPORT_DOC_TYPES.indexOf(doc.docType) !== -1) {
doc.breadCrumbs = [
{ text: 'API', path: '/api' },
{ text: '@angular/' + doc.moduleDoc.id, path: doc.moduleDoc.path },
{ text: doc.name, path: doc.path }
];
}
});
}
};
};

39
aio/tools/transforms/angular-api-package/processors/computeApiBreadCrumbs.spec.js Normal file
View File

@ -0,0 +1,39 @@
const testPackage = require('../../helpers/test-package');
const processorFactory = require('./computeApiBreadCrumbs');
const Dgeni = require('dgeni');
describe('angular-api-package: computeApiBreadCrumbs processor', () => {
it('should be available on the injector', () => {
const dgeni = new Dgeni([testPackage('angular-api-package')]);
const injector = dgeni.configureInjector();
const processor = injector.get('computeApiBreadCrumbs');
expect(processor.$process).toBeDefined();
expect(processor.$runAfter).toEqual(['paths-computed']);
expect(processor.$runBefore).toEqual(['rendering-docs']);
});
it('should attach a breadCrumbs property to each of the EXPORT_DOC_TYPES docs', () => {
const EXPORT_DOC_TYPES = ['class', 'interface'];
const processor = processorFactory(EXPORT_DOC_TYPES);
const docs = [
{ docType: 'class', name: 'ClassA', path: 'module-1/class-a', moduleDoc: { id: 'moduleOne', path: 'module-1' } },
{ docType: 'interface', name: 'InterfaceB', path: 'module-2/interface-b', moduleDoc: { id: 'moduleTwo', path: 'module-2' } },
{ docType: 'guide', name: 'Guide One', path: 'guide/guide-1' },
];
processor.$process(docs);
expect(docs[0].breadCrumbs).toEqual([
{ text: 'API', path: '/api' },
{ text: '@angular/moduleOne', path: 'module-1' },
{ text: 'ClassA', path: 'module-1/class-a' },
]);
expect(docs[1].breadCrumbs).toEqual([
{ text: 'API', path: '/api' },
{ text: '@angular/moduleTwo', path: 'module-2' },
{ text: 'InterfaceB', path: 'module-2/interface-b' },
]);
expect(docs[2].breadCrumbs).toBeUndefined();
});
});

59
aio/tools/transforms/angular-api-package/processors/processClassLikeMembers.js vendored Normal file
View File

@ -0,0 +1,59 @@
/**
* A class like API doc contains members, but these can be either properties or method.
* Separate the members into two new collections: `doc.properties` and `doc.methods`.
*/
module.exports = function processClassLikeMembers() {
return {
$runAfter: ['filterContainedDocs'],
$runBefore: ['rendering-docs'],
$process(docs) {
docs.forEach(doc => {
if (doc.members) {
doc.properties = [];
doc.methods = [];
doc.members.forEach(member => {
if (isMethod(member)) {
doc.methods.push(member);
computeMemberDescription(member);
} else {
doc.properties.push(member);
if (!member.description) {
// Is this property defined as a constructor parameter e.g. `constructor(public property: string) { ... }`?
const constructorDoc = member.containerDoc.constructorDoc;
if (constructorDoc) {
const matchingParameterDoc = constructorDoc.parameterDocs.filter(doc => doc.declaration === member.declaration)[0];
member.constructorParamDoc = matchingParameterDoc;
}
}
}
});
}
if (doc.statics) {
doc.staticProperties = [];
doc.staticMethods = [];
doc.statics.forEach(member => {
if (isMethod(member)) {
doc.staticMethods.push(member);
computeMemberDescription(member);
} else {
doc.staticProperties.push(member);
}
});
}
});
}
};
};
function isMethod(doc) {
return doc.hasOwnProperty('parameters') && !doc.isGetAccessor && !doc.isSetAccessor;
}
function computeMemberDescription(member) {
if (!member.description && member.overloads) {
// Perhaps the description is on one of the overloads - take the first non-empty one
member.description = member.overloads.map(overload => overload.description).filter(description => !!description)[0];
}
}

81
aio/tools/transforms/angular-api-package/processors/processClassLikeMembers.spec.js Normal file
View File

@ -0,0 +1,81 @@
const testPackage = require('../../helpers/test-package');
const processorFactory = require('./processClassLikeMembers');
const Dgeni = require('dgeni');
const property1 = { description: 'property 1' };
const property2 = { description: 'property 2' };
const getter1 = { parameters: [], isGetAccessor: true, description: 'getter 1' };
const setter1 = { parameters: [], isSetAccessor: true, description: 'setter 1' };
const method1 = { parameters: [] };
const method2 = { parameters: [] };
const method3 = { parameters: [] };
describe('angular-api-packge: processClassLikeMembers processor', () => {
it('should be available on the injector', () => {
const dgeni = new Dgeni([testPackage('angular-api-package')]);
const injector = dgeni.configureInjector();
const processor = injector.get('processClassLikeMembers');
expect(processor.$process).toBeDefined();
expect(processor.$runAfter).toEqual(['filterContainedDocs']);
expect(processor.$runBefore).toEqual(['rendering-docs']);
});
it('should copy instance members into properties and methods', () => {
const processor = processorFactory();
const docs = [
{ members: [ property1, method1, getter1] },
{ members: [ method2, property2, method3, setter1] },
{ }
];
processor.$process(docs);
expect(docs[0].properties).toEqual([property1, getter1]);
expect(docs[0].methods).toEqual([method1]);
expect(docs[1].properties).toEqual([property2, setter1]);
expect(docs[1].methods).toEqual([method2, method3]);
expect(docs[2].properties).toBeUndefined();
expect(docs[2].methods).toBeUndefined();
});
it('should copy static members into properties and methods', () => {
const processor = processorFactory();
const docs = [
{ statics: [ property1, method1, getter1] },
{ statics: [ method2, property2, method3, setter1] },
{ }
];
processor.$process(docs);
expect(docs[0].staticProperties).toEqual([property1, getter1]);
expect(docs[0].staticMethods).toEqual([method1]);
expect(docs[1].staticProperties).toEqual([property2, setter1]);
expect(docs[1].staticMethods).toEqual([method2, method3]);
expect(docs[2].staticProperties).toBeUndefined();
expect(docs[2].staticMethods).toBeUndefined();
});
it('should wire up properties that are declared as parameters on the constructor to its associated parameter doc', () => {
const processor = processorFactory();
const propertyDeclaration = {};
const parameterDoc1 = { declaration: {} };
const parameterDoc2 = { declaration: propertyDeclaration };
const parameterDoc3 = { declaration: {} };
const property = {
declaration: propertyDeclaration,
containerDoc: {
constructorDoc: {
parameterDocs: [ parameterDoc1, parameterDoc2, parameterDoc3 ]
}
}
};
const docs = [{ members: [ property] }];
processor.$process(docs);
expect(property.constructorParamDoc).toEqual(parameterDoc2);
});
});

8
aio/tools/transforms/angular-api-package/tag-defs/throws.js vendored Normal file
View File

@ -0,0 +1,8 @@
module.exports = function(extractTypeTransform, wholeTagTransform) {
return {
name: 'throws',
aliases: ['exception'],
multi: true,
transforms: [ extractTypeTransform, wholeTagTransform ]
};
};

45
aio/tools/transforms/templates/api/base.template.html
View File

@ -1,13 +1,46 @@
{% import "lib/githubLinks.html" as github -%}
{% set comma = joiner(',') %}
{% set slash = joiner('/') %}
<article>
<div class="breadcrumb">
<script type="application/ld+json">
{
"@context": "http://schema.org",
"@type": "BreadcrumbList",
"itemListElement": [
{% for crumb in doc.breadCrumbs %}
{$ comma() $}{
"@type": "ListItem",
"position": {$ loop.index $},
"item": {
"@id": "https://angular.io/{$ crumb.path $}",
"name": "{$ crumb.text $}"
}
}{% endfor %}
]
}
</script>
{% for crumb in doc.breadCrumbs %}{% if not loop.last %}
{$ slash() $}
{% if crumb.path %}<a href="{$ crumb.path $}">{$ crumb.text $}<a>{% else %}{$ crumb.text $}{% endif %}
{% endif %}{% endfor %}
</div>
<header class="api-header">
<h1 class="no-toc">{$ doc.name $}</h1>
{% if doc.deprecated !== undefined %}<label class="api-status-label deprecated">deprecated</label>{% endif %}
{% if doc.experimental !== undefined %}<label class="api-status-label experimental">experimental</label>{% endif %}
{% if doc.stable !== undefined %}<label class="api-status-label stable">stable</label>{% endif %}
<label class="api-type-label {$ doc.docType $}">{$ doc.docType $}</label>
{% if doc.deprecated %}<label class="api-status-label deprecated">deprecated</label>{% endif %}
{% if doc.experimental %}<label class="api-status-label experimental">experimental</label>{% endif %}
{% if doc.stable %}<label class="api-status-label stable">stable</label>{% endif %}
<h1>
{$ doc.name $}
</h1>
<span class="version">{$ version $}</span>
</header>
<div class="page-actions">
<a href="#"><label class="raised page-label"><i class="material-icons">mode_edit</i>suggest edits</label></a>
<a href="{$ github.githubHref(doc, versionInfo) $}"><label class="raised page-label"><i class="material-icons">code</i>view source</label></a>
</div>
{% block body %}{% endblock %}
<div class="api-body">
{% block body %}{% endblock %}
</div>
</article>

31
aio/tools/transforms/templates/api/class.template.html
View File

@ -1,16 +1,27 @@
{% import "lib/memberHelpers.html" as memberHelpers -%}
{% import "lib/descendants.html" as descendants -%}
{% import "lib/paramList.html" as params -%}
{% extends 'export-base.template.html' -%}
{% extends 'base.template.html' -%}
{% block overview %}{% include "includes/class-overview.html" %}{% endblock %}
{% block details %}
{% block additional %}{% endblock %}
{% include "includes/description.html" %}
{$ descendants.renderDescendants(doc, 'class', 'Subclasses') $}
{$ memberHelpers.renderMemberDetails(doc.statics, 'static-members', 'static-member', 'Static Members') $}
{% if doc.constructorDoc %}{$ memberHelpers.renderMemberDetails([doc.constructorDoc], 'constructors', 'constructor', 'Constructor') $}{% endif %}
{$ memberHelpers.renderMemberDetails(doc.members, 'instance-members', 'instance-member', 'Members') $}
{% block annotations %}{% include "includes/annotations.html" %}{% endblock %}
{% block body %}
<p>{$ doc.whatItDoes | marked $}</p>
{% include "includes/security-notes.html" %}
{% include "includes/deprecation.html" %}
{% block overview %}
{% include "includes/class-overview.html" %}
{% endblock %}
{% block details %}
{% block additional %}{% endblock %}
{% include "includes/description.html" %}
{$ memberHelpers.renderProperties(doc.staticProperties, 'static-properties', 'static-property', 'Static Properties') $}
{$ memberHelpers.renderMethodDetails(doc.staticMethods, 'static-methods', 'static-method', 'Static Methods') $}
{% if doc.constructorDoc %}{$ memberHelpers.renderMethodDetail(doc.constructorDoc, 'constructor') $}{% endif %}
{$ memberHelpers.renderProperties(doc.properties, 'instance-properties', 'instance-property', 'Properties') $}
{$ memberHelpers.renderMethodDetails(doc.methods, 'instance-methods', 'instance-method', 'Methods') $}
{% block annotations %}{% include "includes/annotations.html" %}{% endblock %}
{% endblock %}
{% include "includes/how-to-use.html" %}
{% endblock %}

2
aio/tools/transforms/templates/api/decorator.template.html
View File

@ -5,5 +5,5 @@
{% block overview %}{% include "includes/decorator-overview.html" %}{% endblock %}
{% block details %}
{% include "includes/description.html" %}
{$ memberHelper.renderMemberDetails(doc.members, 'metadata-members', 'metadata-member', 'Metadata Properties') $}
{$ memberHelper.renderProperties(doc.members, 'metadata-members', 'metadata-member', 'Metadata Properties') $}
{% endblock %}

1
aio/tools/transforms/templates/api/export-base.template.html
View File

@ -1,7 +1,6 @@
{% extends 'base.template.html' -%}
{% block body %}
{% include "includes/info-bar.html" %}
{% include "includes/what-it-does.html" %}
{% include "includes/security-notes.html" %}
{% include "includes/deprecation.html" %}

14
aio/tools/transforms/templates/api/includes/class-overview.html
View File

@ -2,13 +2,23 @@
<section class="{$ doc.docType $}-overview">
<h2>Overview</h2>
{% if (doc.descendants | filterByPropertyValue('docType', 'class')).length or doc.see.length %}
<div class="sidebar">
{$ descendants.renderDescendants(doc, 'class', 'Subclasses') $}
{% include "includes/see-also.html" %}
</div>
{% endif %}
<code-example language="ts" hideCopy="true">
{$ doc.docType $} {$ doc.name $}{$ doc.typeParams | escape $}{$ memberHelper.renderHeritage(doc) $} {
{%- if doc.constructorDoc %}{% if not doc.constructorDoc.internal %}
<a class="code-anchor" href="#{$ doc.constructorDoc.anchor | urlencode $}">{$ memberHelper.renderMember(doc.constructorDoc, 1) $}</a>{% endif %}{% endif -%}
<a class="code-anchor" href="#{$ doc.constructorDoc.anchor | urlencode $}">{$ memberHelper.renderMemberSyntax(doc.constructorDoc, 1) $}</a>{% endif %}{% endif -%}
{%- if doc.statics.length %}{% for member in doc.statics %}{% if not member.internal %}
<a class="code-anchor" href="#{$ member.anchor | urlencode $}">{$ memberHelper.renderMember(member, 1) $}</a>{% endif %}{% endfor %}{% endif -%}
<a class="code-anchor" href="#{$ member.anchor | urlencode $}">{$ memberHelper.renderMemberSyntax(member, 1) $}</a>{% endif %}{% endfor %}{% endif -%}
{$ memberHelper.renderMembers(doc) $}
}
</code-example>
<div class="inline-sidebar">
{$ descendants.renderDescendants(doc, 'class', 'Subclasses') $}
{% include "includes/see-also.html" %}
</div>
</section>

2
aio/tools/transforms/templates/api/includes/directive-overview.html
View File

@ -6,7 +6,7 @@
@{$ decorator.name $}({$ decorator.arguments $}){% endfor %}
class {$ doc.name $}{$ doc.typeParams | escape $}{$ memberHelper.renderHeritage(doc) $} {
{%- if doc.statics.length %}{% for member in doc.statics %}{% if not member.internal %}
<a class="code-anchor" href="#{$ member.anchor | urlencode $}">{$ memberHelper.renderMember(member, 1) $}</a>{% endif %}{% endfor %}{% endif -%}
<a class="code-anchor" href="#{$ member.anchor | urlencode $}">{$ memberHelper.renderMemberSyntax(member, 1) $}</a>{% endif %}{% endfor %}{% endif -%}
{$ memberHelper.renderMembers(doc) $}
}
</code-example>

7
aio/tools/transforms/templates/api/includes/interface-overview.html
View File

@ -2,9 +2,14 @@
<section class="interface-overview">
<h2>Interface Overview</h2>
<div class="sidebar">
{$ descendants.renderDescendants(doc, 'interface', 'Child Interfaces') $}
{$ descendants.renderDescendants(doc, 'class', 'Class Implementations') $}
{% include "includes/see-also.html" %}
</div>
<code-example language="ts" hideCopy="true">
interface {$ doc.name $}{$ doc.typeParams | escape $}{$ memberHelper.renderHeritage(doc) $} { {% if doc.members.length %}{% for member in doc.members %}{% if not member.internal %}
<a class="code-anchor" href="#{$ member.anchor | urlencode $}">{$ memberHelper.renderMember(member, 1) $}</a>{% endif %}{% endfor %}{% endif %}
<a class="code-anchor" href="#{$ member.anchor | urlencode $}">{$ memberHelper.renderMemberSyntax(member, 1) $}</a>{% endif %}{% endfor %}{% endif %}
}
</code-example>
</section>

9
aio/tools/transforms/templates/api/includes/see-also.html Normal file
View File

@ -0,0 +1,9 @@
{%- if doc.see.length %}
<section class="see-also">
<h2>See Also</h2>
<ul>
{% for see in doc.see %}
<li>{$ see | marked $}</li>{% endfor %}
</ul>
</section>
{% endif %}

10
aio/tools/transforms/templates/api/interface.template.html
View File

@ -6,7 +6,11 @@
{% block overview %}{% include "includes/interface-overview.html" %}{% endblock %}
{% block details %}
{% include "includes/description.html" %}
{$ descendants.renderDescendants(doc, 'interface', 'Child Interfaces') $}
{$ descendants.renderDescendants(doc, 'class', 'Class Implementations') $}
{$ memberHelper.renderMemberDetails(doc.members, 'instance-members', 'instance-member', 'Members') $}
<div class="inline-sidebar">
{$ descendants.renderDescendants(doc, 'interface', 'Child Interfaces') $}
{$ descendants.renderDescendants(doc, 'class', 'Class Implementations') $}
{% include "includes/see-also.html" %}
</div>
{$ memberHelper.renderProperties(doc.properties, 'instance-properties', 'instance-property', 'Properties') $}
{$ memberHelper.renderMethodDetails(doc.methods, 'instance-methods', 'instance-method', 'Methods') $}
{% endblock %}

24
aio/tools/transforms/templates/api/lib/descendants.html
View File

@ -1,14 +1,22 @@
{% macro renderDescendants(doc, docType, title='', recursed=false) %}
{% set descendants = doc.descendants | filterByPropertyValue('docType', docType) %}
{% if descendants.length %}
{% if title %}<h2>{$ title $}</h2>{% endif %}
<ul {% if not recursed %}class="descendants {$ docType $}"{% endif %}>
{% macro renderDescendantList(descendants, docType, recursed) %}
{% if descendants.length %}
<ul>
{% for descendant in descendants %}
<li>
<pre class="prettyprint lang-ts"><code>{$ descendant.name $}</code></pre>
{$ renderDescendants(descendant, docType, '', true) $}
<code>{$ descendant.name $}</code>
{$ renderDescendantList(descendant.descendants | filterByPropertyValue('docType', docType), docType, recursed) $}
</li>
{% endfor %}
</ul>
</ul>
{% endif %}
{% endmacro -%}
{%- macro renderDescendants(doc, docType, title='', recursed=true) %}
{% set descendants = doc.descendants | filterByPropertyValue('docType', docType) %}
{% if descendants.length %}
<div class="descendants {$ docType $}">
{% if title %}<h2>{$ title $}</h2>{% endif %}
{$ renderDescendantList(descendants, docType, recursed) $}
</div>
{% endif %}
{% endmacro %}

122
aio/tools/transforms/templates/api/lib/memberHelpers.html
View File

@ -11,12 +11,12 @@
{%- macro renderMembers(doc) -%}
{%- if doc.members.length %}{% for member in doc.members %}{% if not member.internal %}
<a class="code-anchor" href="{$ doc.path $}#{$ member.anchor | urlencode $}">{$ renderMember(member, 1) $}</a>{% endif %}{% endfor %}{% endif %}
<a class="code-anchor" href="{$ doc.path $}#{$ member.anchor | urlencode $}">{$ renderMemberSyntax(member, 1) $}</a>{% endif %}{% endfor %}{% endif %}
{%- for ancestor in doc.extendsClauses %}{% if ancestor.doc %}
// inherited from <a class="code-anchor" href="{$ ancestor.doc.path $}">{$ ancestor.doc.id $}</a>{$ renderMembers(ancestor.doc) $}{% endif %}{% endfor %}
{%- endmacro -%}
{%- macro renderMember(member, truncateLines) -%}
{%- macro renderMemberSyntax(member, truncateLines) -%}
{%- if member.accessibility !== 'public' %}{$ member.accessibility $} {% endif -%}
{%- if (member.isGetAccessor or member.isReadonly) and not member.isSetAccessor %}get {% endif -%}
{%- if member.isSetAccessor and not member.isGetAccessor %}set {% endif -%}
@ -26,35 +26,101 @@
{$ params.returnType(member.type) | trim | truncateCode(truncateLines) $}
{%- endmacro -%}
{%- macro renderMemberDetail(member, cssClass) -%}
<div class="{$ cssClass $}">
<a id="{$ member.anchor $}"></a>
<code-example language="ts" hideCopy="true" class="no-box api-heading">{$ renderMember(member) $}</code-example>
{%- if not member.notYetDocumented %}
{$ member.description | marked $}
{% endif -%}
</div>
{%- macro renderOverloadInfo(overload, cssClass, method) -%}
{% if overload.description and (overload.description != method.description) %}{$ overload.description | marked $}{% endif %}
<code-example language="ts" hideCopy="true" class="no-box api-heading">{$ renderMemberSyntax(overload) $}</code-example>
<h4 class="no-anchor">Parameters</h4>
{$ params.renderParameters(overload.parameterDocs, cssClass + '-parameters', cssClass + '-parameter') $}
{% if overload.type or overload.returns.type %}
<h4 class="no-anchor">Returns</h4>
{% marked %}`{$ (overload.type or overload.returns.type) $}`{% if overload.returns %}: {$ overload.returns.description $}{% endif %}{% endmarked %}
{% endif %}
{% if overload.throws.length %}
<h4 class="no-anchor">Throws</h4>
{% for error in overload.throws %}
{% marked %}`{$ (error.typeList or 'Error') $}` {$ error.description $}{% endmarked %}
{% endfor %}
{% endif %}
{%- endmacro -%}
{%- macro renderMethodDetail(method, cssClass) -%}
<a id="{$ method.anchor $}"></a>
<table class="is-full-width method-table {$ cssClass $}">
<thead><tr><th><h3>{$ method.name $}()</h3></th></tr></thead>
<tbody>
<tr>
<td>
{% if method.description %}{$ method.description | marked $}{% endif %}
</td>
</tr>
{% if method.overloads.length == 0 %}
<tr>
<td>
{$ renderOverloadInfo(method, cssClass + '-overload', method) $}
</td>
</tr>
{% elseif method.overloads.length < 3 -%}
{% for overload in method.overloads -%}
<tr>
<td>
{$ renderOverloadInfo(overload, cssClass + '-overload', method) $}
</td>
</tr>
{% endfor -%}
{% else -%}
<tr>
<td>
<details class="overloads">
<summary><h4 class="no-anchor">{$ method.overloads.length $} overloads...</h4></summary>
<div class="detail-contents">
{% for overload in method.overloads %}
{$ renderOverloadInfo(overload, cssClass + '-overload', method) $}
{% if not loop.last %}<hr class="hr-margin fullwidth">{% endif %}
{% endfor %}
</div>
</details>
</td>
</tr>
{% endif %}
</tbody>
</table>
{% endmacro -%}
{% macro renderMemberDetails(members, containerClass, itemClass, titleText) %}
{% if members.length %}
{%- macro renderMethodDetails(methods, containerClass, itemClass, headingText) -%}
{% if methods.length %}
<section class="{$ containerClass $}">
<h2>{$ titleText $}</h2>
{% for member in members %}{% if not member.internal %}
{$ renderMemberDetail(member, itemClass) $}
{% if member.overloads.length %}
<details class="overloads">
<summary>Overloads</summary>
<div class="detail-contents">
{% for overload in member.overloads %}
{$ renderMemberDetail(overload, itemClass + '-overload') $}
{% if not loop.last %}<hr>{% endif %}
{% endfor %}
</div>
</details>
{% endif %}
{% if not loop.last %}<hr class="hr-margin">{% endif %}
<h2>{$ headingText $}</h2>
{% for member in methods %}{% if not member.internal %}
{$ renderMethodDetail(member, itemClass) $}
{% endif %}{% endfor %}
</section>
{% endif %}
{% endmacro %}
{%- endmacro -%}
{%- macro renderProperties(properties, containerClass, propertyClass, headingText) -%}
{%- if properties.length -%}
<h2>{$ headingText $}</h2>
<table class="is-full-width list-table properties-table">
<thead>
<tr><th>Property</th><th>Type</th><th>Description</th></tr>
</thead>
<tbody>
{% for property in properties %}{% if not property.internal %}
<tr class="{$ propertyClass $}">
<td><a id="{$ property.anchor $}"></a>{$ property.name $}</td>
<td><label class="property-type-label"><code>{$ property.type | escape $}</code></label></td>
<td>
{$ (property.description or property.constructorParamDoc.description) | marked $}
{% if property.constructorParamDoc %} <span class='from-constructor'>Declared in constructor.</span>{% endif %}
</td>
</tr>
{% endif %}{% endfor %}
</tbody>
</table>
{%- endif -%}
{%- endmacro -%}

20
aio/tools/transforms/templates/api/lib/paramList.html
View File

@ -10,3 +10,23 @@
{% macro returnType(returnType) -%}
{%- if returnType %}: {$ returnType | escape $}{% endif -%}
{%- endmacro -%}
{%- macro renderParameters(parameters, containerClass, parameterClass) -%}
{%- if parameters.length -%}
<table class="is-full-width list-table parameters-table {$ containerClass $}">
<tbody>
{% for parameter in parameters %}
<tr class="{$ parameterClass $}">
<td class="param-name"><a id="{$ parameter.anchor $}"></a>{$ parameter.name $}</td>
<td class="param-description">
{% if parameter.description | trim %}{$ parameter.description | marked $}
{% elseif parameter.type %}<code>{$ parameter.type $}</code>
{% endif %}
</td>
</tr>{% endfor %}
</tbody>
</table>
{%- else -%}
<p>There are no parameters.</p>
{%- endif -%}
{%- endmacro -%}