Skip to content

Commit 3d550d0

Browse files
jelbournjelbourn
authored
chore: improve dgeni api doc gen (#2312)
1 parent c10f1f7 commit 3d550d0

File tree

8 files changed

+150
-78
lines changed

8 files changed

+150
-78
lines changed

‎tools/dgeni/index.js

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -130,6 +130,9 @@ let apiDocsPackage = new DgeniPackage('material2-api-docs', dgeniPackageDeps)
130130
'common.template.html'
131131
];
132132

133+
// dgeni disables autoescape by default, but we want this turned on.
134+
templateEngine.config.autoescape = true;
135+
133136
// Nunjucks and Angular conflict in their template bindings so change Nunjucks
134137
templateEngine.config.tags = {
135138
variableStart: '{$',

‎tools/dgeni/processors/categorizer.js

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,10 @@ module.exports = function categorizer() {
3434
doc.isNgModule = true;
3535
} else if (doc.docType == 'member') {
3636
doc.isDirectiveInput = isDirectiveInput(doc);
37+
doc.directiveInputAlias = getDirectiveInputAlias(doc);
38+
3739
doc.isDirectiveOutput = isDirectiveOutput(doc);
40+
doc.directiveOutputAlias = getDirectiveOutputAlias(doc);
3841

3942
doc.classDoc.properties ?
4043
doc.classDoc.properties.push(doc) :
@@ -61,6 +64,14 @@ function normalizeMethodParameters(method) {
6164
method.parameters.forEach(parameter => {
6265
let [parameterName, parameterType] = parameter.split(':');
6366

67+
// If the parameter is optional, the name here will contain a '?'. We store whether the
68+
// parameter is optional and remove the '?' for comparison.
69+
let isOptional = false;
70+
if (parameterName.includes('?')) {
71+
isOptional = true;
72+
parameterName = parameterName.replace('?', '');
73+
}
74+
6475
if (!method.params) {
6576
method.params = [];
6677
}
@@ -73,6 +84,7 @@ function normalizeMethodParameters(method) {
7384
}
7485

7586
jsDocParam.type = parameterType.trim();
87+
jsDocParam.isOptional = isOptional;
7688
});
7789
}
7890
}
@@ -97,6 +109,14 @@ function isDirectiveInput(doc) {
97109
return hasMemberDecorator(doc, 'Input');
98110
}
99111

112+
function getDirectiveInputAlias(doc) {
113+
return isDirectiveInput(doc) ? doc.decorators.find(d => d.name == 'Input').arguments[0] : '';
114+
}
115+
116+
function getDirectiveOutputAlias(doc) {
117+
return isDirectiveOutput(doc) ? doc.decorators.find(d => d.name == 'Output').arguments[0] : '';
118+
}
119+
100120
function hasMemberDecorator(doc, decoratorName) {
101121
return doc.docType == 'member' && hasDecorator(doc, decoratorName);
102122
}

‎tools/dgeni/templates/class.template.html

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
<h4>{$ class.name $}</h4>
2+
<p> {$ class.description $} </p>
3+
4+
{$ propertyList(class.properties) $}
5+
6+
{$ methodList(class.methods) $}

‎tools/dgeni/templates/componentGroup.template.html

Lines changed: 41 additions & 78 deletions
Original file line numberDiff line numberDiff line change
@@ -11,81 +11,44 @@
1111
}
1212
</style>
1313

14-
<h2>{$ doc.name $}</h2>
15-
<p> Module: <code>{$ doc.ngModule.name $}</code> </p>
16-
17-
<h3>Directives</h3>
18-
19-
{% for directive in doc.directives %}
20-
<h4>{$ directive.name $}</h4>
21-
<p> {$ directive.description $} </p>
22-
23-
{%- if directive.properties.length -%}
24-
<h5> Properties </h5>
25-
<table>
26-
<tr>
27-
<th>Name</th>
28-
<th>Description</th>
29-
</tr>
30-
{% for property in directive.properties %}
31-
<tr>
32-
<td>
33-
{%- if property.isDirectiveInput -%}
34-
<p>@Input</p>
35-
{%- endif -%}
36-
37-
<p>{$ property.name $}</p>
38-
<p><code>{$ property.type $}</code></p>
39-
</td>
40-
<td> {$ property.description $}</td>
41-
</tr>
42-
{% endfor %}
43-
</table>
44-
{%- endif -%}
45-
46-
{%- if directive.methods.length -%}
47-
<h5> Methods </h5>
48-
{% for method in directive.methods %}
49-
<table>
50-
<tr>
51-
<th colspan="2">{$ method.name $}</th>
52-
</tr>
53-
<tr>
54-
<td colspan="2"> {$ method.description $} </td>
55-
</tr>
56-
57-
{%- if method.params.length -%}
58-
<tr>
59-
<th colspan="2"> Parameters </th>
60-
</tr>
61-
{% for parameter in method.params %}
62-
<tr>
63-
<td>
64-
<p>{$ parameter.name $}</p>
65-
<p>{$ parameter.type $}</p>
66-
</td>
67-
<td>
68-
{$ parameter.description $}
69-
</td>
70-
</tr>
71-
{% endfor %}
72-
{%- endif -%}
73-
74-
{%- if method.showReturns -%}
75-
<tr>
76-
<th colspan="2"> Returns </th>
77-
</tr>
78-
<tr>
79-
<td>{$ method.returnType $}</td>
80-
<td>{$ method.returns.description $}</td>
81-
</tr>
82-
{%- endif -%}
83-
</table>
84-
{% endfor %}
85-
{%- endif -%}
86-
87-
{% endfor %}
88-
89-
90-
91-
14+
{# Defines macros for reusable templates. #}
15+
{% macro method(method) -%}
16+
{% include 'method.template.html' %}
17+
{% endmacro %}
18+
19+
{% macro property(property) -%}
20+
{% include 'property.template.html' %}
21+
{% endmacro %}
22+
23+
{% macro methodList(methodList) -%}
24+
{% include 'method-list.template.html' %}
25+
{% endmacro %}
26+
27+
{% macro propertyList(propertyList) -%}
28+
{% include 'property-list.template.html' %}
29+
{% endmacro %}
30+
31+
{% macro class(class) -%}
32+
{% include 'class.template.html' %}
33+
{% endmacro %}
34+
35+
<h1>{$ doc.name $}</h1>
36+
<h2>
37+
Module: <code>{$ doc.ngModule.name $}</code>
38+
</h2>
39+
40+
41+
{%- if doc.services.length -%}
42+
<h2>Services</h2>
43+
{% for service in doc.services %}
44+
{$ class(service) $}
45+
{% endfor %}
46+
{%- endif -%}
47+
48+
49+
{%- if doc.directives.length -%}
50+
<h2>Directives</h2>
51+
{% for directive in doc.directives %}
52+
{$ class(directive) $}
53+
{% endfor %}
54+
{%- endif -%}

‎tools/dgeni/templates/method-list.template.html

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
{%- if methodList.length -%}
2+
<h5> Methods </h5>
3+
{% for m in methodList %}
4+
{$ method(m) $}
5+
{% endfor %}
6+
{%- endif -%}

‎tools/dgeni/templates/method.template.html

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
<table>
2+
<tr>
3+
<th colspan="2">{$ method.name $}</th>
4+
</tr>
5+
<tr>
6+
<td colspan="2"> {$ method.description $}</td>
7+
</tr>
8+
9+
{%- if method.params.length -%}
10+
<tr>
11+
<th colspan="2"> Parameters</th>
12+
</tr>
13+
{% for parameter in method.params %}
14+
<tr>
15+
<td>
16+
<p>
17+
{$ parameter.name $}
18+
{%- if parameter.isOptional -%}
19+
<span>?</span>
20+
{%- endif -%}
21+
</p>
22+
<p>{$ parameter.type $}</p>
23+
</td>
24+
<td>
25+
{$ parameter.description $}
26+
</td>
27+
</tr>
28+
{% endfor %}
29+
{%- endif -%}
30+
31+
{%- if method.showReturns -%}
32+
<tr>
33+
<th colspan="2"> Returns</th>
34+
</tr>
35+
<tr>
36+
<td>{$ method.returnType $}</td>
37+
<td>{$ method.returns.description $}</td>
38+
</tr>
39+
{%- endif -%}
40+
</table>

‎tools/dgeni/templates/property-list.template.html

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
{%- if propertyList.length -%}
2+
<h5> Properties </h5>
3+
<table>
4+
<tr>
5+
<th>Name</th>
6+
<th>Description</th>
7+
</tr>
8+
{% for p in propertyList %}
9+
{$ property(p) $}
10+
{% endfor %}
11+
</table>
12+
{%- endif -%}

‎tools/dgeni/templates/property.template.html

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
<tr>
2+
<td>
3+
{%- if property.isDirectiveInput -%}
4+
{%- if property.directiveInputAlias -%}
5+
<p>@Input({$ property.directiveInputAlias $})</p>
6+
{% else %}
7+
<p>@Input()</p>
8+
{%- endif -%}
9+
{%- endif -%}
10+
{%- if property.isDirectiveOutput -%}
11+
{%- if property.directiveOutputAlias -%}
12+
<p>@Output({$ property.directiveOutputAlias $})</p>
13+
{% else %}
14+
<p>@Output()</p>
15+
{%- endif -%}
16+
{%- endif -%}
17+
18+
<p>{$ property.name $}</p>
19+
<p><code>{$ property.type $}</code></p>
20+
</td>
21+
<td> {$ property.description $}</td>
22+
</tr>

0 commit comments

Comments
 (0)