diff --git a/docs/dgeni-package/index.js b/docs/dgeni-package/index.js index db3c8c60ad..97dd7f6ce4 100644 --- a/docs/dgeni-package/index.js +++ b/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) { diff --git a/docs/dgeni-package/processors/attachModuleDocs.js b/docs/dgeni-package/processors/attachModuleDocs.js new file mode 100644 index 0000000000..8c0d960e17 --- /dev/null +++ b/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; + }); + } + }; +}; diff --git a/docs/dgeni-package/processors/processClassDocs.js b/docs/dgeni-package/processors/captureClassMembers.js similarity index 92% rename from docs/dgeni-package/processors/processClassDocs.js rename to docs/dgeni-package/processors/captureClassMembers.js index 71598d6693..ba280a21a7 100644 --- a/docs/dgeni-package/processors/processClassDocs.js +++ b/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 = []; diff --git a/docs/dgeni-package/processors/captureModuleDocs.js b/docs/dgeni-package/processors/captureModuleDocs.js new file mode 100644 index 0000000000..8d3c9c9a4f --- /dev/null +++ b/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); + } + }); + } + }; +}; \ No newline at end of file diff --git a/docs/dgeni-package/processors/processModuleDocs.js b/docs/dgeni-package/processors/captureModuleExports.js similarity index 80% rename from docs/dgeni-package/processors/processModuleDocs.js rename to docs/dgeni-package/processors/captureModuleExports.js index 52db81b056..000912d540 100644 --- a/docs/dgeni-package/processors/processModuleDocs.js +++ b/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); } }; }; \ No newline at end of file diff --git a/docs/dgeni-package/processors/cloneExportedFromDocs.js b/docs/dgeni-package/processors/cloneExportedFromDocs.js new file mode 100644 index 0000000000..e647d7caa8 --- /dev/null +++ b/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; + } + }; +}; \ No newline at end of file diff --git a/docs/dgeni-package/processors/createOverviewDump.js b/docs/dgeni-package/processors/createOverviewDump.js index c0c1d60d08..0d72844bf5 100644 --- a/docs/dgeni-package/processors/createOverviewDump.js +++ b/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 = { diff --git a/docs/dgeni-package/processors/generateDocsFromComments.js b/docs/dgeni-package/processors/generateDocsFromComments.js deleted file mode 100644 index 5d8b682c66..0000000000 --- a/docs/dgeni-package/processors/generateDocsFromComments.js +++ /dev/null @@ -1,34 +0,0 @@ -var _ = require('lodash'); - -module.exports = function generateDocsFromComments(log) { - return { - $runAfter: ['files-read'], - $runBefore: ['parsing-tags'], - $process: function(docs) { - var commentDocs = []; - docs = _.filter(docs, function(doc) { - if (doc.docType !== 'atScriptFile') { - return true; - } else { - _.forEach(doc.fileInfo.comments, function(comment) { - - // we need to check for `/**` at the start of the comment to find all the jsdoc style comments - comment.range.toString().replace(/^\/\*\*([\w\W]*)\*\/$/g, function(match, commentBody) { - - // Create a doc from this comment - commentDocs.push({ - fileInfo: doc.fileInfo, - startingLine: comment.range.start.line, - endingLine: comment.range.end.line, - content: commentBody, - codeTree: comment.treeAfter, - docType: 'atScriptDoc' - }); - }); - }); - } - }); - return docs.concat(commentDocs); - } - }; -}; \ No newline at end of file diff --git a/docs/dgeni-package/tag-defs/exportedAs.js b/docs/dgeni-package/tag-defs/exportedAs.js new file mode 100644 index 0000000000..aa36151697 --- /dev/null +++ b/docs/dgeni-package/tag-defs/exportedAs.js @@ -0,0 +1,4 @@ +module.exports = { + name: 'exportedAs', + multi: true +}; \ No newline at end of file diff --git a/docs/dgeni-package/tag-defs/public.js b/docs/dgeni-package/tag-defs/public.js new file mode 100644 index 0000000000..a85d5dd43c --- /dev/null +++ b/docs/dgeni-package/tag-defs/public.js @@ -0,0 +1,4 @@ +module.exports = { + name: 'public', + transforms: function(doc, tag) { return true; } +}; \ No newline at end of file diff --git a/docs/dgeni-package/templates/overview-dump.template.html b/docs/dgeni-package/templates/overview-dump.template.html index 52eaf8ca91..3f4ee1294f 100644 --- a/docs/dgeni-package/templates/overview-dump.template.html +++ b/docs/dgeni-package/templates/overview-dump.template.html @@ -23,7 +23,7 @@ {% for module in doc.modules %}

{$ module.id $} - {%- if module.publicModule %} (public){% endif %}

+ {%- if module.public %} (public){% endif %} {% for export in module.exports %}

{$ export.name $}

diff --git a/docs/public-docs-package/index.js b/docs/public-docs-package/index.js index da001e7a1f..dbc3c9fcf1 100644 --- a/docs/public-docs-package/index.js +++ b/docs/public-docs-package/index.js @@ -6,12 +6,11 @@ module.exports = new Package('angular-public', [basePackage]) .processor(require('./processors/filterPublicDocs')) -.config(function(processClassDocs, filterPublicDocs, EXPORT_DOC_TYPES) { - processClassDocs.ignorePrivateMembers = true; - filterPublicDocs.docTypes = EXPORT_DOC_TYPES; +.config(function(captureClassMembers) { + captureClassMembers.ignorePrivateMembers = true; }) // Configure file writing .config(function(writeFilesProcessor) { writeFilesProcessor.outputFolder = 'dist/public_docs'; -}); +}); \ No newline at end of file diff --git a/docs/public-docs-package/processors/filterPublicDocs.js b/docs/public-docs-package/processors/filterPublicDocs.js index 4190f2e740..8d290f0e36 100644 --- a/docs/public-docs-package/processors/filterPublicDocs.js +++ b/docs/public-docs-package/processors/filterPublicDocs.js @@ -1,63 +1,28 @@ var _ = require('lodash'); -module.exports = function filterPublicDocs(modules) { +module.exports = function filterPublicDocs(modules, EXPORT_DOC_TYPES) { return { - $runAfter: ['tags-parsed'], + $runAfter: ['tags-parsed', 'cloneExportedFromDocs'], $runBefore: ['computing-ids'], - docTypes: [], - $validate: { - docTypes: { presence: true } - }, $process: function(docs) { - var extraPublicDocs = []; - docTypes = this.docTypes; - - _.forEach(docs, function(doc) { - - if (docTypes.indexOf(doc.docType) === -1 || !doc.publicModule) return; - - var publicModule = modules[doc.publicModule]; - - if (!publicModule) { - throw new Error('Missing module definition: "' + doc.publicModule + '"\n' + - 'Referenced in class: "' + doc.moduleDoc.id + '/' + doc.name + '"'); - } else { - - // Ensure module is marked as public - publicModule.isPublic = true; - - // Add a clone of export to its "public" module - var publicDoc = _.clone(doc); - publicDoc.moduleDoc = publicModule; - publicModule.exports.push(publicDoc); - extraPublicDocs.push(publicDoc); - } - }); - // Filter out the documents that are not public - docs = _.filter(docs, function(doc) { + return _.filter(docs, function(doc) { if (doc.docType === 'module') { // doc is a module - is it public? - return doc.isPublic; + return doc.public; } - if (docTypes.indexOf(doc.docType) === -1) { + if (EXPORT_DOC_TYPES.indexOf(doc.docType) === -1) { // doc is not a type we care about return true; } // doc is in a public module - return doc.moduleDoc && doc.moduleDoc.isPublic; + return doc.moduleDoc && doc.moduleDoc.public; }); - - docs = docs.concat(extraPublicDocs); - - return docs; } }; - - }; \ No newline at end of file diff --git a/modules/angular2/angular2.js b/modules/angular2/angular2.js index afc531b739..86a7965ec7 100644 --- a/modules/angular2/angular2.js +++ b/modules/angular2/angular2.js @@ -1,8 +1,12 @@ /** + * @module + * @public + * @description * Define public API for Angular here. */ export * from './change_detection'; export * from './core'; export * from './annotations'; +export * from './template'; export * from './directives'; export * from './forms'; diff --git a/modules/angular2/annotations.js b/modules/angular2/annotations.js index d95c56a360..6673bcdd6b 100644 --- a/modules/angular2/annotations.js +++ b/modules/angular2/annotations.js @@ -1,4 +1,7 @@ /** + * @module + * @public + * @description * Define public API for Angular here. */ export * from './src/core/annotations/annotations'; diff --git a/modules/angular2/change_detection.js b/modules/angular2/change_detection.js index a6ff92d713..c4a89eb72b 100644 --- a/modules/angular2/change_detection.js +++ b/modules/angular2/change_detection.js @@ -1,3 +1,10 @@ +/** + * @module + * @public + * @description + * Description of the change_detection module + */ + export { ASTWithSource, AST, AstTransformer, AccessMember, LiteralArray, ImplicitReceiver } from './src/change_detection/parser/ast'; @@ -45,7 +52,7 @@ export var defaultPipes = { /** - * @publicModule angular2/change_detection + * @exportedAs angular2/change_detection */ export class DynamicChangeDetection extends ChangeDetection { registry:PipeRegistry; @@ -61,7 +68,7 @@ export class DynamicChangeDetection extends ChangeDetection { } /** - * @publicModule angular2/change_detection + * @exportedAs angular2/change_detection */ export class JitChangeDetection extends ChangeDetection { registry:PipeRegistry; diff --git a/modules/angular2/di.js b/modules/angular2/di.js index f54eb8cace..89ebdc5aea 100644 --- a/modules/angular2/di.js +++ b/modules/angular2/di.js @@ -1,3 +1,9 @@ +/** + * @module + * @description + * This is a description + */ + export {Inject, InjectPromise, InjectLazy, Injectable, Optional, DependencyAnnotation} from './src/di/annotations'; export {Injector} from './src/di/injector'; export {Binding, Dependency, bind} from './src/di/binding'; diff --git a/modules/angular2/directives.js b/modules/angular2/directives.js index 54d259c559..29ed4027c5 100644 --- a/modules/angular2/directives.js +++ b/modules/angular2/directives.js @@ -1,3 +1,10 @@ +/** + * @module + * @public + * @description + * Describe the directives module here + */ + export * from './src/directives/class'; export * from './src/directives/for'; export * from './src/directives/if'; diff --git a/modules/angular2/forms.js b/modules/angular2/forms.js index 40f02caae1..80309a3789 100644 --- a/modules/angular2/forms.js +++ b/modules/angular2/forms.js @@ -1,3 +1,10 @@ +/** + * @module + * @public + * @description + * Describe the forms module here + */ + export * from './src/forms/model'; export * from './src/forms/directives'; export * from './src/forms/validators'; diff --git a/modules/angular2/pipes.js b/modules/angular2/pipes.js index 1f650590e0..6492c1f35c 100644 --- a/modules/angular2/pipes.js +++ b/modules/angular2/pipes.js @@ -1,3 +1,6 @@ /** + * @module + * @public + * @description * Define public API for Angular here. */ diff --git a/modules/angular2/src/change_detection/binding_propagation_config.js b/modules/angular2/src/change_detection/binding_propagation_config.js index 282b31d279..66730d19d4 100644 --- a/modules/angular2/src/change_detection/binding_propagation_config.js +++ b/modules/angular2/src/change_detection/binding_propagation_config.js @@ -2,7 +2,7 @@ import {ChangeDetector} from './interfaces'; import {CHECK_ONCE, DETACHED, CHECK_ALWAYS} from './constants'; /** - * @publicModule angular2/change_detection + * @exportedAs angular2/change_detection */ export class BindingPropagationConfig { _cd:ChangeDetector; diff --git a/modules/angular2/src/change_detection/pipes/iterable_changes.js b/modules/angular2/src/change_detection/pipes/iterable_changes.js index 8df99e7bf7..4ab8bf0110 100644 --- a/modules/angular2/src/change_detection/pipes/iterable_changes.js +++ b/modules/angular2/src/change_detection/pipes/iterable_changes.js @@ -27,7 +27,7 @@ export class IterableChangesFactory { } /** - * @publicModule angular2/pipes + * @exportedAs angular2/pipes */ export class IterableChanges extends Pipe { _collection; @@ -505,7 +505,7 @@ export class IterableChanges extends Pipe { } /** - * @publicModule angular2/pipes + * @exportedAs angular2/pipes */ export class CollectionChangeRecord { currentIndex:int; diff --git a/modules/angular2/src/change_detection/pipes/keyvalue_changes.js b/modules/angular2/src/change_detection/pipes/keyvalue_changes.js index f3b2739d89..155dd21ab5 100644 --- a/modules/angular2/src/change_detection/pipes/keyvalue_changes.js +++ b/modules/angular2/src/change_detection/pipes/keyvalue_changes.js @@ -4,7 +4,7 @@ import {stringify, looseIdentical, isJsObject} from 'angular2/src/facade/lang'; import {NO_CHANGE, Pipe} from './pipe'; /** - * @publicModule angular2/pipes + * @exportedAs angular2/pipes */ export class KeyValueChangesFactory { supports(obj):boolean { @@ -17,7 +17,7 @@ export class KeyValueChangesFactory { } /** - * @publicModule angular2/pipes + * @exportedAs angular2/pipes */ export class KeyValueChanges extends Pipe { _records:Map; @@ -356,7 +356,7 @@ export class KeyValueChanges extends Pipe { /** - * @publicModule angular2/pipes + * @exportedAs angular2/pipes */ export class KVChangeRecord { key; diff --git a/modules/angular2/src/change_detection/pipes/null_pipe.js b/modules/angular2/src/change_detection/pipes/null_pipe.js index 9c51fea64e..de6728ebad 100644 --- a/modules/angular2/src/change_detection/pipes/null_pipe.js +++ b/modules/angular2/src/change_detection/pipes/null_pipe.js @@ -2,7 +2,7 @@ import {isBlank} from 'angular2/src/facade/lang'; import {Pipe, NO_CHANGE} from './pipe'; /** - * @publicModule angular2/pipes + * @exportedAs angular2/pipes */ export class NullPipeFactory { supports(obj):boolean { @@ -15,7 +15,7 @@ export class NullPipeFactory { } /** - * @publicModule angular2/pipes + * @exportedAs angular2/pipes */ export class NullPipe extends Pipe { called:boolean; diff --git a/modules/angular2/src/change_detection/pipes/pipe.js b/modules/angular2/src/change_detection/pipes/pipe.js index af0a62134d..da3f189319 100644 --- a/modules/angular2/src/change_detection/pipes/pipe.js +++ b/modules/angular2/src/change_detection/pipes/pipe.js @@ -1,7 +1,7 @@ export var NO_CHANGE = new Object(); /** - * @publicModule angular2/angular2 + * @exportedAs angular2/angular2 */ export class Pipe { supports(obj):boolean {return false;} diff --git a/modules/angular2/src/core/annotations/annotations.js b/modules/angular2/src/core/annotations/annotations.js index d48fe35bc6..c2a32d038b 100644 --- a/modules/angular2/src/core/annotations/annotations.js +++ b/modules/angular2/src/core/annotations/annotations.js @@ -232,7 +232,7 @@ import {Injectable} from 'angular2/di'; * This directive would be instantiated with a `Dependency` directive found on the current element. If none can be * found, the injector supplies `null` instead of throwing an error. * - * @publicModule angular2/annotations + * @exportedAs angular2/annotations */ @ABSTRACT() export class Directive extends Injectable { @@ -478,7 +478,7 @@ export class Directive extends Injectable { * } * ``` * - * @publicModule angular2/annotations + * @exportedAs angular2/annotations */ export class Component extends Directive { /** @@ -614,7 +614,7 @@ export class Component extends Directive { * * * - * @publicModule angular2/annotations + * @exportedAs angular2/annotations */ export class DynamicComponent extends Directive { /** @@ -706,7 +706,7 @@ export class DynamicComponent extends Directive { *
* ``` * - * @publicModule angular2/annotations + * @exportedAs angular2/annotations */ export class Decorator extends Directive { @@ -832,7 +832,7 @@ export class Decorator extends Directive { * view occurs on the second `
  • ` which is a sibling to the `