From d4ffa47ea6908b5f09db23bf95bcbce93dd0b0ed Mon Sep 17 00:00:00 2001 From: Pete Bacon Darwin Date: Tue, 7 Feb 2017 08:04:25 +0000 Subject: [PATCH] fix(aio): correctly render decorator docs (#14328) 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 https://github.com/angular/angular.io/pull/2349 --- docs/templates/includes/_metadata.html | 4 +- .../processors/mergeDecoratorDocs.js | 66 ++++++++----------- .../processors/mergeDecoratorDocs.spec.js | 18 ++--- 3 files changed, 35 insertions(+), 53 deletions(-) diff --git a/docs/templates/includes/_metadata.html b/docs/templates/includes/_metadata.html index f9c7e3abc1..5bca45a8e7 100644 --- 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 %}

Metadata Properties

- {% for metadata in doc.metadataDoc.members %}{% if not metadata.internal %} + {% for metadata in doc.members %}{% if not metadata.internal %} 
diff --git a/tools/docs/angular.io-package/processors/mergeDecoratorDocs.js b/tools/docs/angular.io-package/processors/mergeDecoratorDocs.js
index bd7cfcd8f4..03e55cfc4a 100644
--- 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
index 4819f98ad6..67c456e7d5 100644
--- 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');
   });
 });
\ No newline at end of file