fix(aio): correctly render decorator docs (angular#14328)

petebacondarwin · IgorMinar · commit d4ffa47ea690 · 2017-02-07T00:04:25.000-08:00
This commit updates the doc-gen to account for the changes to the codebase for decorators. There are actually three kinds of calls that create decorators: * makeDecorator * makePropDecorator * makeParamDecorator Also, the actual documentation for each decorator is split between two exported symbols: * `interface [DecoratorName]` contains the metadata fields * interface [DecoratorName]Decorator` contains a "call member" which holds the general description of the decorator. This processor now identifies all three decorator types, and pulls the description of the callMember onto the main decorator doc description. (There are some outstanding interfaces in the angular/angular project that need to be re-exported from `/angular/modules/@angular/core/src/metadata.ts` to ensure that the doc-gen is able to access them.) Closes angular/angular.io#2349
diff --git a/docs/templates/includes/_metadata.html b/docs/templates/includes/_metadata.html
@@ -1,8 +1,8 @@
-{% if doc.metadataDoc and doc.metadataDoc.members.length %}
+{% if doc.members.length %}
 <section class="meta-data">
   <h2>Metadata Properties</h2>
   <div class="description">
-    {% for metadata in doc.metadataDoc.members %}{% if not metadata.internal %}
+    {% for metadata in doc.members %}{% if not metadata.internal %}
     <div class="metadata-member">
       <a name="{$ metadata.name $}-anchor" class="anchor-offset"></a>
       <pre class="prettyprint no-bg" ng-class="{ 'anchor-focused': appCtrl.isApiDocMemberFocused('{$ metadata.name $}') }">
diff --git a/tools/docs/angular.io-package/processors/mergeDecoratorDocs.js b/tools/docs/angular.io-package/processors/mergeDecoratorDocs.js
@@ -1,61 +1,47 @@
 var _ = require('lodash');
 
-module.exports = function mergeDecoratorDocs() {
+module.exports = function mergeDecoratorDocs(log) {
   return {
     $runAfter: ['processing-docs'],
     $runBefore: ['docs-processed'],
-    docsToMergeInfo: [
-      {nameTemplate: _.template('${name}Decorator'), decoratorProperty: 'decoratorInterfaceDoc'}, {
-        nameTemplate: _.template('${name}Metadata'),
-        decoratorProperty: 'metadataDoc',
-        useFields: ['howToUse', 'whatItDoes']
-      },
-      {nameTemplate: _.template('${name}MetadataType'), decoratorProperty: 'metadataInterfaceDoc'},
-      {
-        nameTemplate: _.template('${name}MetadataFactory'),
-        decoratorProperty: 'metadataFactoryDoc'
-      }
+    makeDecoratorCalls: [
+      {type: '', description: 'toplevel'},
+      {type: 'Prop', description: 'property'},
+      {type: 'Param', description: 'parameter'},
     ],
     $process: function(docs) {
 
-      var docsToMergeInfo = this.docsToMergeInfo;
+      var makeDecoratorCalls = this.makeDecoratorCalls;
       var docsToMerge = Object.create(null);
 
       docs.forEach(function(doc) {
 
-        // find all the decorators, signified by a call to `makeDecorator(metadata)`
-        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;
+        makeDecoratorCalls.forEach(function(call) {
+          // find all the decorators, signified by a call to `makeDecorator(metadata)`
+          var makeDecorator = getMakeDecoratorCall(doc, call.type);
+          if (makeDecorator) {
+            log.debug('mergeDecoratorDocs: found decorator', doc.docType, doc.name);
+            doc.docType = 'decorator';
+            doc.decoratorLocation = call.description;
+            // 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) {
-            docsToMerge[info.nameTemplate({name: doc.name})] = {
-              decoratorDoc: doc,
-              property: info.decoratorProperty
-            };
-          });
-        }
+            // keep track of the names of the docs that need to be merged into this decorator doc
+            docsToMerge[doc.name + 'Decorator'] = doc;
+          }
+        });
       });
 
       // merge the metadata docs into the decorator docs
       docs = docs.filter(function(doc) {
         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]; });
-          }
+          var decoratorDoc = docsToMerge[doc.name];
+          log.debug(
+              'mergeDecoratorDocs: merging', doc.name, 'into', decoratorDoc.name,
+              doc.callMember.description.substring(0, 50));
+          decoratorDoc.description = doc.callMember.description;
 
           // remove doc from its module doc's exports
           doc.moduleDoc.exports =
diff --git a/tools/docs/angular.io-package/processors/mergeDecoratorDocs.spec.js b/tools/docs/angular.io-package/processors/mergeDecoratorDocs.spec.js
@@ -2,7 +2,7 @@ var testPackage = require('../../helpers/test-package');
 var Dgeni = require('dgeni');
 
 describe('mergeDecoratorDocs processor', function() {
-  var dgeni, injector, processor, decoratorDoc, otherDoc;
+  var dgeni, injector, processor, decoratorDoc, decoratorDocWithTypeAssertion, otherDoc;
 
   beforeEach(function() {
     dgeni = new Dgeni([testPackage('angular.io-package')]);
@@ -13,9 +13,8 @@ describe('mergeDecoratorDocs processor', function() {
       name: 'X',
       docType: 'var',
       exportSymbol: {
-        valueDeclaration: {
-          initializer: {expression: {text: 'makeDecorator'}, arguments: [{text: 'XMetadata'}]}
-        }
+        valueDeclaration:
+            {initializer: {expression: {text: 'makeDecorator'}, arguments: [{text: 'X'}]}}
       }
     };
 
@@ -25,11 +24,8 @@ describe('mergeDecoratorDocs processor', function() {
       exportSymbol: {
         valueDeclaration: {
           initializer: {
-            expression: {
-              type: {},
-              expression: {text: 'makeDecorator'},
-              arguments: [{text: 'YMetadata'}]
-            }
+            expression:
+                {type: {}, expression: {text: 'makeDecorator'}, arguments: [{text: 'Y'}]}
           }
         }
       }
@@ -55,7 +51,7 @@ describe('mergeDecoratorDocs processor', function() {
 
   it('should extract the "type" of the decorator meta data', function() {
     processor.$process([decoratorDoc, decoratorDocWithTypeAssertion, otherDoc]);
-    expect(decoratorDoc.decoratorType).toEqual('XMetadata');
-    expect(decoratorDocWithTypeAssertion.decoratorType).toEqual('YMetadata');
+    expect(decoratorDoc.decoratorType).toEqual('X');
+    expect(decoratorDocWithTypeAssertion.decoratorType).toEqual('Y');
   });
 });
