chore: improve dgeni api doc gen

src/lib/snack-bar/snack-bar-container.ts

@@ -33,6 +33,7 @@ export const HIDE_ANIMATION = '195ms cubic-bezier(0.0,0.0,0.2,1)';
 
 /**
  * Internal component that wraps user-provided snack bar content.
+ * @docs-private
  */
 @Component({
   moduleId: module.id,

tools/dgeni/index.js

@@ -130,6 +130,9 @@ let apiDocsPackage = new DgeniPackage('material2-api-docs', dgeniPackageDeps)
     'common.template.html'
   ];
 
+  // dgeni disables autoescape by default, but we want this turned on.
+  templateEngine.config.autoescape = true;
+
   // Nunjucks and Angular conflict in their template bindings so change Nunjucks
   templateEngine.config.tags = {
     variableStart: '{$',

tools/dgeni/processors/categorizer.js

@@ -34,7 +34,10 @@ module.exports = function categorizer() {
           doc.isNgModule = true;
         } else if (doc.docType == 'member') {
           doc.isDirectiveInput = isDirectiveInput(doc);
+          doc.directiveInputAlias = getDirectiveInputAlias(doc);
+
           doc.isDirectiveOutput = isDirectiveOutput(doc);
+          doc.directiveOutputAlias = getDirectiveOutputAlias(doc);
 
           doc.classDoc.properties ?
               doc.classDoc.properties.push(doc) :
@@ -61,6 +64,14 @@ function normalizeMethodParameters(method) {
     method.parameters.forEach(parameter => {
       let [parameterName, parameterType] = parameter.split(':');
 
+      // If the parameter is optional, the name here will contain a '?'. We store whether the
+      // parameter is optional and remove the '?' for comparison.
+      let isOptional = false;
+      if (parameterName.includes('?')) {
+        isOptional = true;
+        parameterName = parameterName.replace('?', '');
+      }
+
       if (!method.params) {
         method.params = [];
       }
@@ -73,6 +84,7 @@ function normalizeMethodParameters(method) {
       }
 
       jsDocParam.type = parameterType.trim();
+      jsDocParam.isOptional = isOptional;
     });
   }
 }
@@ -97,6 +109,14 @@ function isDirectiveInput(doc) {
   return hasMemberDecorator(doc, 'Input');
 }
 
+function getDirectiveInputAlias(doc) {
+  return isDirectiveInput(doc) ? doc.decorators.find(d => d.name == 'Input').arguments[0] : '';
+}
+
+function getDirectiveOutputAlias(doc) {
+  return isDirectiveOutput(doc) ? doc.decorators.find(d => d.name == 'Output').arguments[0] : '';
+}
+
 function hasMemberDecorator(doc, decoratorName) {
   return doc.docType == 'member' && hasDecorator(doc, decoratorName);
 }

tools/dgeni/templates/class.template.html

@@ -0,0 +1,6 @@
+<h4>{$ class.name $}</h4>
+<p> {$ class.description $} </p>
+
+{$ propertyList(class.properties) $}
+
+{$ methodList(class.methods) $}

tools/dgeni/templates/componentGroup.template.html

@@ -11,81 +11,44 @@
   }
 </style>
 
-<h2>{$ doc.name $}</h2>
-<p> Module: <code>{$ doc.ngModule.name $}</code> </p>
-
-<h3>Directives</h3>
-
-{% for directive in doc.directives %}
-  <h4>{$ directive.name $}</h4>
-  <p> {$ directive.description $} </p>
-
-  {%- if directive.properties.length -%}
-    <h5> Properties </h5>
-    <table>
-      <tr>
-        <th>Name</th>
-        <th>Description</th>
-      </tr>
-      {% for property in directive.properties %}
-        <tr>
-          <td>
-            {%- if property.isDirectiveInput -%}
-              <p>@Input</p>
-            {%- endif -%}
-
-            <p>{$ property.name $}</p>
-            <p><code>{$ property.type $}</code></p>
-          </td>
-          <td> {$ property.description $}</td>
-        </tr>
-      {% endfor %}
-    </table>
-  {%- endif -%}
-
-  {%- if directive.methods.length -%}
-    <h5> Methods </h5>
-    {% for method in directive.methods %}
-    <table>
-      <tr>
-        <th colspan="2">{$ method.name $}</th>
-      </tr>
-      <tr>
-        <td colspan="2"> {$ method.description $} </td>
-      </tr>
-
-      {%- if method.params.length -%}
-        <tr>
-          <th colspan="2"> Parameters </th>
-        </tr>
-        {% for parameter in method.params %}
-          <tr>
-            <td>
-              <p>{$ parameter.name $}</p>
-              <p>{$ parameter.type $}</p>
-            </td>
-            <td>
-              {$ parameter.description $}
-            </td>
-          </tr>
-        {% endfor %}
-      {%- endif -%}
-
-      {%- if method.showReturns -%}
-        <tr>
-          <th colspan="2"> Returns </th>
-        </tr>
-        <tr>
-          <td>{$ method.returnType $}</td>
-          <td>{$ method.returns.description $}</td>
-        </tr>
-      {%- endif -%}
-    </table>
-    {% endfor %}
-  {%- endif -%}
-
-{% endfor %}
-
-
-
-
+{# Defines macros for reusable templates. #}
+{% macro method(method) -%}
+  {% include 'method.template.html' %}
+{% endmacro %}
+
+{% macro property(property) -%}
+  {% include 'property.template.html' %}
+{% endmacro %}
+
+{% macro methodList(methodList) -%}
+  {% include 'method-list.template.html' %}
+{% endmacro %}
+
+{% macro propertyList(propertyList) -%}
+  {% include 'property-list.template.html' %}
+{% endmacro %}
+
+{% macro class(class) -%}
+  {% include 'class.template.html' %}
+{% endmacro %}
+
+<h1>{$ doc.name $}</h1>
+<h2>
+  Module: <code>{$ doc.ngModule.name $}</code>
+</h2>
+
+
+{%- if doc.services.length -%}
+  <h2>Services</h2>
+  {% for service in doc.services %}
+    {$ class(service) $}
+  {% endfor %}
+{%- endif -%}
+
+
+{%- if doc.directives.length -%}
+  <h2>Directives</h2>
+  {% for directive in doc.directives %}
+    {$ class(directive) $}
+  {% endfor %}
+{%- endif -%}

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

@@ -0,0 +1,6 @@
+{%- if methodList.length -%}
+  <h5> Methods </h5>
+  {% for m in methodList %}
+    {$ method(m) $}
+  {% endfor %}
+{%- endif -%}

tools/dgeni/templates/method.template.html

@@ -0,0 +1,40 @@
+<table>
+  <tr>
+    <th colspan="2">{$ method.name $}</th>
+  </tr>
+  <tr>
+    <td colspan="2"> {$ method.description $}</td>
+  </tr>
+
+  {%- if method.params.length -%}
+  <tr>
+    <th colspan="2"> Parameters</th>
+  </tr>
+  {% for parameter in method.params %}
+  <tr>
+    <td>
+      <p>
+        {$ parameter.name $}
+        {%- if parameter.isOptional -%}
+          <span>?</span>
+        {%- endif -%}
+      </p>
+      <p>{$ parameter.type $}</p>
+    </td>
+    <td>
+      {$ parameter.description $}
+    </td>
+  </tr>
+  {% endfor %}
+  {%- endif -%}
+
+  {%- if method.showReturns -%}
+  <tr>
+    <th colspan="2"> Returns</th>
+  </tr>
+  <tr>
+    <td>{$ method.returnType $}</td>
+    <td>{$ method.returns.description $}</td>
+  </tr>
+  {%- endif -%}
+</table>

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

@@ -0,0 +1,12 @@
+{%- if propertyList.length -%}
+  <h5> Properties </h5>
+  <table>
+    <tr>
+      <th>Name</th>
+      <th>Description</th>
+    </tr>
+    {% for p in propertyList %}
+      {$ property(p) $}
+    {% endfor %}
+  </table>
+{%- endif -%}

tools/dgeni/templates/property.template.html

@@ -0,0 +1,22 @@
+<tr>
+  <td>
+    {%- if property.isDirectiveInput -%}
+      {%- if property.directiveInputAlias -%}
+        <p>@Input({$ property.directiveInputAlias $})</p>
+      {% else %}
+        <p>@Input()</p>
+      {%- endif -%}
+    {%- endif -%}
+    {%- if property.isDirectiveOutput -%}
+      {%- if property.directiveOutputAlias -%}
+        <p>@Output({$ property.directiveOutputAlias $})</p>
+      {% else %}
+        <p>@Output()</p>
+      {%- endif -%}
+    {%- endif -%}
+
+    <p>{$ property.name $}</p>
+    <p><code>{$ property.type $}</code></p>
+  </td>
+  <td> {$ property.description $}</td>
+</tr>