docs(test_lib/test_injector): fix invalid jsdoc type

chore(doc-gen): capture docs for modules from comments

Closes angular#1258

docs(*): add module description jsdoc tags
docs(*): add @public tag to public modules
chore(doc-gen): fix overview-dump template
The template was referencing an invalid property
chore(doc-gen): use `@exportedAs` and `@public` rather than `@publicModule`

This commit refactors how we describe components that are re-exported in another
module. For example the "public" modules like `angular/angular` and `angular/annotations`
are public but they only re-export components from "private" modules.

Previously, you must apply the `@publicModule` tag to a component that was to be
re-exported. Applying this tag caused the destination module to become public.

Now, you specify that a module is public by applying the `@public` tag and then
you can "re-export" components to other modules by applying the `@exportedAs`
giving the name of the module from which the component will be re-exported.
tag. This tag can be used multiple times on a single component, allowing the
component to be exported on multiple modules.

docs(*): rename `@publicModule` to `@exportedAs`

The `@publicModule` dgeni tag has been replaced by the `@exportedAs`
dgeni tag on components that are to be re-exported on another module.

Closes angular#1290

Author: petebacondarwin

docs/dgeni-package/index.js

@@ -37,13 +37,16 @@ module.exports = new Package('angular', [jsdocPackage, nunjucksPackage])
 
 
 // Register the processors
-.processor(require('./processors/generateDocsFromComments'))
-.processor(require('./processors/processModuleDocs'))
-.processor(require('./processors/processClassDocs'))
+.processor(require('./processors/captureModuleExports'))
+.processor(require('./processors/captureClassMembers'))
+.processor(require('./processors/captureModuleDocs'))
+.processor(require('./processors/attachModuleDocs'))
+.processor(require('./processors/cloneExportedFromDocs'))
 .processor(require('./processors/generateNavigationDoc'))
 .processor(require('./processors/extractTitleFromGuides'))
 .processor(require('./processors/createOverviewDump'))
 
+
 // Configure the log service
 .config(function(log) {
   log.level = 'warning';
@@ -63,6 +66,12 @@ module.exports = new Package('angular', [jsdocPackage, nunjucksPackage])
 })
 
 
+.config(function(parseTagsProcessor, getInjectables) {
+  parseTagsProcessor.tagDefinitions.push(require('./tag-defs/public'));
+  parseTagsProcessor.tagDefinitions.push(require('./tag-defs/exportedAs'));
+})
+
+
 // Configure file writing
 .config(function(writeFilesProcessor) {
   writeFilesProcessor.outputFolder  = 'dist/docs';
@@ -90,10 +99,6 @@ module.exports = new Package('angular', [jsdocPackage, nunjucksPackage])
   ];
 })
 
-// Add in a custom tag that we use when generating public docs
-.config(function(parseTagsProcessor) {
-  parseTagsProcessor.tagDefinitions.push({ name: 'publicModule' });
-})
 
 // Configure ids and paths
 .config(function(computeIdsProcessor, computePathsProcessor, EXPORT_DOC_TYPES) {

docs/dgeni-package/processors/attachModuleDocs.js

@@ -0,0 +1,22 @@
+var _ = require('lodash');
+
+module.exports = function attachModuleDocs(log) {
+
+  return {
+    $runAfter: ['tags-extracted'],
+    $runBefore: ['computing-ids'],
+    $process: function(docs) {
+      return _.filter(docs, function(doc) {
+        if (doc.docType !== 'moduleDoc') {
+          return true;
+        }
+        if (doc.module || doc.module === '') {
+          doc.moduleDoc.description = doc.description;
+          doc.moduleDoc.public = doc.public;
+          log.debug('attached', doc.moduleDoc.id, doc.moduleDoc.description);
+        }
+        return false;
+      });
+    }
+  };
+};

docs/dgeni-package/processors/processClassDocs.js renamed to docs/dgeni-package/processors/captureClassMembers.js

@@ -1,10 +1,10 @@
 var _ = require('lodash');
 
-module.exports = function processClassDocs(log, getJSDocComment) {
+module.exports = function captureClassMembers(log, getJSDocComment) {
 
   return {
-    $runAfter: ['processModuleDocs'],
-    $runBefore: ['parsing-tags', 'generateDocsFromComments'],
+    $runAfter: ['captureModuleExports'],
+    $runBefore: ['parsing-tags'],
     ignorePrivateMembers: false,
     $process: function(docs) {
       var memberDocs = [];

docs/dgeni-package/processors/captureModuleDocs.js

@@ -0,0 +1,31 @@
+var _ = require('lodash');
+
+module.exports = function captureModuleDocs(log, getJSDocComment) {
+
+  return {
+    $runAfter: ['captureClassMembers'],
+    $runBefore: ['parsing-tags'],
+    $process: function(docs) {
+      // Generate docs for each module's file's comments not already captured
+      _.forEach(docs, function(moduleDoc) {
+
+        if ( moduleDoc.docType !== 'module' ) return;
+
+        moduleDoc.extraComments = [];
+        _.forEach(moduleDoc.comments, function(comment) {
+          var jsDocComment = getJSDocComment(comment);
+          if (jsDocComment) {
+            jsDocComment.docType = 'moduleDoc';
+            jsDocComment.moduleDoc = moduleDoc;
+            moduleDoc.extraComments.push(jsDocComment);
+            docs.push(jsDocComment);
+//            console.log('found', jsDocComment.content);
+          }
+        });
+        if ( moduleDoc.extraComments.length > 0 ) {
+//          console.log(moduleDoc.extraComments.length);
+        }
+      });
+    }
+  };
+};

docs/dgeni-package/processors/processModuleDocs.js renamed to docs/dgeni-package/processors/captureModuleExports.js

@@ -1,12 +1,12 @@
 var _ = require('lodash');
 
-module.exports = function processModuleDocs(log, ExportTreeVisitor, getJSDocComment) {
+module.exports = function captureModuleExports(log, ExportTreeVisitor, getJSDocComment) {
 
   return {
     $runAfter: ['files-read'],
-    $runBefore: ['parsing-tags', 'generateDocsFromComments'],
+    $runBefore: ['parsing-tags'],
     $process: function(docs) {
-      var exportDocs = [];
+      var extraDocs = [];
       _.forEach(docs, function(doc) {
         if ( doc.docType === 'module' ) {
 
@@ -21,7 +21,7 @@ module.exports = function processModuleDocs(log, ExportTreeVisitor, getJSDocComm
             _.forEach(visitor.exports, function(exportDoc) {
 
               doc.exports.push(exportDoc);
-              exportDocs.push(exportDoc);
+              extraDocs.push(exportDoc);
               exportDoc.moduleDoc = doc;
 
               if (exportDoc.comment) {
@@ -40,7 +40,7 @@ module.exports = function processModuleDocs(log, ExportTreeVisitor, getJSDocComm
         }
       });
 
-      return docs.concat(exportDocs);
+      return docs.concat(extraDocs);
     }
   };
 };

docs/dgeni-package/processors/cloneExportedFromDocs.js

@@ -0,0 +1,37 @@
+var _ = require('lodash');
+
+module.exports = function cloneExportedFromDocs(modules, EXPORT_DOC_TYPES) {
+  return {
+    $runAfter: ['tags-parsed', 'attachModuleDocs'],
+    $runBefore: ['computing-ids'],
+    $process: function(docs) {
+
+      var extraPublicDocs = [];
+
+      _.forEach(docs, function(doc) {
+
+        if (EXPORT_DOC_TYPES.indexOf(doc.docType) === -1 || !doc.exportedAs) return;
+
+        _.forEach(doc.exportedAs, function(exportedAs) {
+          var exportedAsModule = modules[exportedAs];
+
+          if (!exportedAsModule) {
+            throw new Error('Missing module definition: "' + doc.exportedAs + '"\n' +
+                            'Referenced in "@exportedAs" tag on class: "' + doc.moduleDoc.id + '/' + doc.name + '"');
+          } else {
+
+            // Add a clone of export to its "exportedAs" module
+            var clonedDoc = _.clone(doc);
+            clonedDoc.moduleDoc = exportedAsModule;
+            exportedAsModule.exports.push(clonedDoc);
+            extraPublicDocs.push(clonedDoc);
+          }
+        });
+      });
+
+      docs = docs.concat(extraPublicDocs);
+
+      return docs;
+    }
+  };
+};

docs/dgeni-package/processors/createOverviewDump.js

@@ -3,7 +3,7 @@ var _ = require('lodash');
 module.exports = function createOverviewDump() {
 
   return {
-    $runAfter: ['processModuleDocs', 'processClassDocs'],
+    $runAfter: ['captureModuleExports', 'captureClassMembers'],
     $runBefore: ['docs-processed'],
     $process: function(docs) {
       var overviewDoc = {

docs/dgeni-package/processors/generateDocsFromComments.js

@@ -0,0 +1,4 @@
+module.exports = {
+  name: 'exportedAs',
+  multi: true
+};

docs/dgeni-package/tag-defs/exportedAs.js

@@ -0,0 +1,4 @@
+module.exports = {
+  name: 'public',
+  transforms: function(doc, tag) { return true; }
+};