api-builder: show metadata details on decorator docs

Author: petebacondarwin

tools/api-builder/angular.io-package/templates/decorator.template.html

@@ -15,16 +15,36 @@
 
 div(layout="row" layout-xs="column" class="row-margin ng-cloak")
   div(flex="20" flex-xs="100")
-    h2(class="h2-api-docs") Variable Export
+    h2(class="h2-api-docs") Description
   div(class="code-links" flex="80" flex-xs="100")
-    pre.prettyprint.no-bg
-      code.
-        export {$ doc.name $}(options : {@link {$ doc.decoratorType $} {$ doc.decoratorType | escape $}}){$ params.returnType(doc.returnType) $}
     :marked
       {%- if not doc.notYetDocumented %}
 {$ doc.description | indentForMarkdown(6) | trimBlankLines $}
       {% endif %}
 
+{% if doc.metadataDoc and doc.metadataDoc.members.length %}
+div(layout="row" layout-xs="column" class="metadata" class="row-margin ng-cloak")
+  div(flex="20" flex-xs="100")
+    h2(class="h2-api-docs") Metadata Properties
+  div(class="code-links" flex="80" flex-xs="100")
+    {% for metadata in doc.metadataDoc.members %}{% if not metadata.internal %}
+    a(name="{$ metadata.name $}-anchor" class="anchor-offset")
+    pre(class="prettyprint no-bg" ng-class="{ 'anchor-focused': appCtrl.isApiDocMemberFocused('{$ metadata.name $}') }")
+      code(class="api-doc-code").
+        {$ metadata.name $}{$ params.paramList(metadata.parameters) | indent(8, false) | trim $}{$ params.returnType(metadata.returnType) $}
+
+    :marked
+      {%- if not metadata.notYetDocumented %}
+{$ metadata.description | indentForMarkdown(6) | replace('### Example', '') | replace('## Example', '') | replace('# Example', '') | trimBlankLines $}
+      {% endif -%}
+
+    {% if not loop.last %}
+    .hr(class="hr-margin")
+    {% endif %}
+
+  {% endif %}{% endfor %}
+{% endif %}
+
 p.location-badge.
   exported from {@link {$ doc.moduleDoc.id $} {$doc.moduleDoc.id $} } defined in {$ github.githubViewLink(doc) $}
 

tools/api-builder/docs-package/processors/mergeDecoratorDocs.js

@@ -6,7 +6,7 @@ module.exports = function mergeDecoratorDocs() {
     $runBefore: ['docs-processed'],
     docsToMergeInfo: [
       { nameTemplate: _.template('${name}Decorator'), decoratorProperty: 'decoratorInterfaceDoc' },
-      { nameTemplate: _.template('${name}Metadata'), decoratorProperty: 'metadataDoc' },
+      { nameTemplate: _.template('${name}Metadata'), decoratorProperty: 'metadataDoc', useFields: ['howToUse', 'whatItDoes'] },
       { nameTemplate: _.template('${name}MetadataType'), decoratorProperty: 'metadataInterfaceDoc' },
       { nameTemplate: _.template('${name}MetadataFactory'), decoratorProperty: 'metadataFactoryDoc' }
     ],
@@ -21,7 +21,10 @@ module.exports = function mergeDecoratorDocs() {
         var makeDecorator = getMakeDecoratorCall(doc);
         if (makeDecorator) {
           doc.docType = 'decorator';
+          // get the type of the decorator metadata
           doc.decoratorType = makeDecorator.arguments[0].text;
+          // clear the symbol type named (e.g. ComponentMetadataFactory) since it is not needed
+          doc.symbolTypeName = undefined;
 
           // keep track of the docs that need to be merged into this decorator doc
           docsToMergeInfo.forEach(function(info) {
@@ -35,13 +38,22 @@ module.exports = function mergeDecoratorDocs() {
         if (docsToMerge[doc.name]) {
           var decoratorDoc = docsToMerge[doc.name].decoratorDoc;
           var property = docsToMerge[doc.name].property;
+          var useFields = docsToMerge[doc.name].useFields;
 
           // attach this document to its decorator
           decoratorDoc[property] = doc;
 
+          // Copy over fields from the merged doc if specified
+          if (useFields) {
+            useFields.forEach(function(field) {
+              decoratorDoc[field] = doc[field];
+            });
+          }
+
           // remove doc from its module doc's exports
           doc.moduleDoc.exports = doc.moduleDoc.exports.filter(function(exportDoc) { return exportDoc !== doc; });
 
+
           // remove from the overall list of docs to be rendered
           return false;
         }