honeymoose
/
angular-cn
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

build(aio): compute and display short descriptions in methods (#22583) 

Previously only export docs were displaying a short description.
Now methods in classes and interfaces also compute and render
the short description.

Closes #22500

PR Close #22583
This commit is contained in:
Pete Bacon Darwin 2018-03-04 20:57:42 +00:00 committed by Alex Eagle
parent d0db9ded90
commit b3d1761825
2 changed files with 36 additions and 19 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -94,7 +94,7 @@ module.exports = new Package('angular-api', [basePackage, typeScriptPackage])
.config(function(splitDescription, EXPORT_DOC_TYPES) { .config(function(splitDescription, EXPORT_DOC_TYPES) {
// Only split the description on the API docs // Only split the description on the API docs
splitDescription.docTypes = EXPORT_DOC_TYPES; splitDescription.docTypes = EXPORT_DOC_TYPES.concat(['member', 'function-overload']);
}) })
.config(function(computePathsProcessor, EXPORT_DOC_TYPES, generateApiListDoc) { .config(function(computePathsProcessor, EXPORT_DOC_TYPES, generateApiListDoc) {
@ -130,6 +130,6 @@ module.exports = new Package('angular-api', [basePackage, typeScriptPackage])
]); ]);
convertToJsonProcessor.docTypes = convertToJsonProcessor.docTypes.concat(DOCS_TO_CONVERT); convertToJsonProcessor.docTypes = convertToJsonProcessor.docTypes.concat(DOCS_TO_CONVERT);
postProcessHtml.docTypes = convertToJsonProcessor.docTypes.concat(DOCS_TO_CONVERT); postProcessHtml.docTypes = convertToJsonProcessor.docTypes.concat(DOCS_TO_CONVERT);
autoLinkCode.docTypes = DOCS_TO_CONVERT.concat(['member']); autoLinkCode.docTypes = DOCS_TO_CONVERT.concat(['member', 'function-overload']);
autoLinkCode.codeElements = ['code', 'code-example', 'code-pane']; autoLinkCode.codeElements = ['code', 'code-example', 'code-pane'];
}); });

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

@ -38,24 +38,35 @@
{%- endmacro -%} {%- endmacro -%}
{%- macro renderOverloadInfo(overload, cssClass, method) -%} {%- 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> <code-example language="ts" hideCopy="true" class="no-box api-heading">{$ renderMemberSyntax(overload) $}</code-example>
<h4 class="no-anchor">Parameters</h4> {% if overload.shortDescription and (overload.shortDescription != method.shortDescription) %}
{$ params.renderParameters(overload.parameterDocs, cssClass + '-parameters', cssClass + '-parameter') $} <div class="short-description">
{$ overload.shortDescription | marked $}
</div>{% endif %}
{% if overload.type or overload.returns.type %} <h4 class="no-anchor">Parameters</h4>
<h4 class="no-anchor">Returns</h4> {$ params.renderParameters(overload.parameterDocs, cssClass + '-parameters', cssClass + '-parameter') $}
{% marked %}`{$ (overload.type or overload.returns.type) $}`{% if overload.returns %}: {$ overload.returns.description $}{% endif %}{% endmarked %}
{% endif %}
{% if overload.throws.length %} {% if overload.type or overload.returns.type %}
<h4 class="no-anchor">Throws</h4> <h4 class="no-anchor">Returns</h4>
{% for error in overload.throws %} {% marked %}`{$ (overload.type or overload.returns.type) $}`{% if overload.returns %}: {$ overload.returns.description $}{% endif %}{% endmarked %}
{% marked %}`{$ (error.typeList or 'Error') $}` {$ error.description $}{% endmarked %} {% endif %}
{% endfor %}
{% 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 %}
{% if overload.description and (overload.description != method.description) -%}
<div class="description">
{$ overload.description | marked $}
</div>
{%- endif %}
{%- endmacro -%} {%- endmacro -%}
{%- macro renderMethodDetail(method, cssClass) -%} {%- macro renderMethodDetail(method, cssClass) -%}
@ -68,9 +79,9 @@
{% endif %} {% endif %}
</h3></th></tr></thead>{% endif %} </h3></th></tr></thead>{% endif %}
<tbody> <tbody>
{% if method.description %}<tr> {% if method.shortDescription %}<tr>
<td> <td class="short-description">
{$ method.description | marked $} {$ method.shortDescription | marked $}
</td> </td>
</tr>{% endif %} </tr>{% endif %}
{% if method.overloads.length == 0 %} {% if method.overloads.length == 0 %}
@ -102,6 +113,11 @@
</td> </td>
</tr> </tr>
{% endif %} {% endif %}
{% if method.description %}<tr>
<td class="description">
{$ method.description | marked $}
</td>
</tr>{% endif %}
</tbody> </tbody>
</table> </table>
{% endmacro -%} {% endmacro -%}
@ -135,6 +151,7 @@
<td><label class="property-type-label"><code>{$ property.type | escape $}</code></label></td> <td><label class="property-type-label"><code>{$ property.type | escape $}</code></label></td>
<td> <td>
{%- if (property.isGetAccessor or property.isReadonly) and not property.isSetAccessor %}<span class='read-only-property'>Read-only.</span>{% endif %} {%- if (property.isGetAccessor or property.isReadonly) and not property.isSetAccessor %}<span class='read-only-property'>Read-only.</span>{% endif %}
{% if property.shortDescription %}{$ property.shortDescription | marked $}{% endif %}
{$ (property.description or property.constructorParamDoc.description) | marked $} {$ (property.description or property.constructorParamDoc.description) | marked $}
{% if property.constructorParamDoc %} <span class='from-constructor'>Declared in constructor.</span>{% endif %} {% if property.constructorParamDoc %} <span class='from-constructor'>Declared in constructor.</span>{% endif %}
</td> </td>