Skip to content

Commit b5002fb

Browse files
petebacondarwinmhevery
petebacondarwin
authored and
mhevery
committed
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
1 parent 8212757 commit b5002fb

47 files changed

Lines changed: 228 additions & 149 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎docs/dgeni-package/index.js‎

Lines changed: 12 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -37,13 +37,16 @@ module.exports = new Package('angular', [jsdocPackage, nunjucksPackage])
3737

3838

3939
// Register the processors
40-
.processor(require('./processors/generateDocsFromComments'))
41-
.processor(require('./processors/processModuleDocs'))
42-
.processor(require('./processors/processClassDocs'))
40+
.processor(require('./processors/captureModuleExports'))
41+
.processor(require('./processors/captureClassMembers'))
42+
.processor(require('./processors/captureModuleDocs'))
43+
.processor(require('./processors/attachModuleDocs'))
44+
.processor(require('./processors/cloneExportedFromDocs'))
4345
.processor(require('./processors/generateNavigationDoc'))
4446
.processor(require('./processors/extractTitleFromGuides'))
4547
.processor(require('./processors/createOverviewDump'))
4648

49+
4750
// Configure the log service
4851
.config(function(log) {
4952
log.level = 'warning';
@@ -63,6 +66,12 @@ module.exports = new Package('angular', [jsdocPackage, nunjucksPackage])
6366
})
6467

6568

69+
.config(function(parseTagsProcessor, getInjectables) {
70+
parseTagsProcessor.tagDefinitions.push(require('./tag-defs/public'));
71+
parseTagsProcessor.tagDefinitions.push(require('./tag-defs/exportedAs'));
72+
})
73+
74+
6675
// Configure file writing
6776
.config(function(writeFilesProcessor) {
6877
writeFilesProcessor.outputFolder = 'dist/docs';
@@ -90,10 +99,6 @@ module.exports = new Package('angular', [jsdocPackage, nunjucksPackage])
9099
];
91100
})
92101

93-
// Add in a custom tag that we use when generating public docs
94-
.config(function(parseTagsProcessor) {
95-
parseTagsProcessor.tagDefinitions.push({ name: 'publicModule' });
96-
})
97102

98103
// Configure ids and paths
99104
.config(function(computeIdsProcessor, computePathsProcessor, EXPORT_DOC_TYPES) {

‎docs/dgeni-package/processors/attachModuleDocs.js‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
var _ = require('lodash');
2+
3+
module.exports = function attachModuleDocs(log) {
4+
5+
return {
6+
$runAfter: ['tags-extracted'],
7+
$runBefore: ['computing-ids'],
8+
$process: function(docs) {
9+
return _.filter(docs, function(doc) {
10+
if (doc.docType !== 'moduleDoc') {
11+
return true;
12+
}
13+
if (doc.module || doc.module === '') {
14+
doc.moduleDoc.description = doc.description;
15+
doc.moduleDoc.public = doc.public;
16+
log.debug('attached', doc.moduleDoc.id, doc.moduleDoc.description);
17+
}
18+
return false;
19+
});
20+
}
21+
};
22+
};

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

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
11
var _ = require('lodash');
22

3-
module.exports = function processClassDocs(log, getJSDocComment) {
3+
module.exports = function captureClassMembers(log, getJSDocComment) {
44

55
return {
6-
$runAfter: ['processModuleDocs'],
7-
$runBefore: ['parsing-tags', 'generateDocsFromComments'],
6+
$runAfter: ['captureModuleExports'],
7+
$runBefore: ['parsing-tags'],
88
ignorePrivateMembers: false,
99
$process: function(docs) {
1010
var memberDocs = [];

‎docs/dgeni-package/processors/captureModuleDocs.js‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
var _ = require('lodash');
2+
3+
module.exports = function captureModuleDocs(log, getJSDocComment) {
4+
5+
return {
6+
$runAfter: ['captureClassMembers'],
7+
$runBefore: ['parsing-tags'],
8+
$process: function(docs) {
9+
// Generate docs for each module's file's comments not already captured
10+
_.forEach(docs, function(moduleDoc) {
11+
12+
if ( moduleDoc.docType !== 'module' ) return;
13+
14+
moduleDoc.extraComments = [];
15+
_.forEach(moduleDoc.comments, function(comment) {
16+
var jsDocComment = getJSDocComment(comment);
17+
if (jsDocComment) {
18+
jsDocComment.docType = 'moduleDoc';
19+
jsDocComment.moduleDoc = moduleDoc;
20+
moduleDoc.extraComments.push(jsDocComment);
21+
docs.push(jsDocComment);
22+
// console.log('found', jsDocComment.content);
23+
}
24+
});
25+
if ( moduleDoc.extraComments.length > 0 ) {
26+
// console.log(moduleDoc.extraComments.length);
27+
}
28+
});
29+
}
30+
};
31+
};

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

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,12 @@
11
var _ = require('lodash');
22

3-
module.exports = function processModuleDocs(log, ExportTreeVisitor, getJSDocComment) {
3+
module.exports = function captureModuleExports(log, ExportTreeVisitor, getJSDocComment) {
44

55
return {
66
$runAfter: ['files-read'],
7-
$runBefore: ['parsing-tags', 'generateDocsFromComments'],
7+
$runBefore: ['parsing-tags'],
88
$process: function(docs) {
9-
var exportDocs = [];
9+
var extraDocs = [];
1010
_.forEach(docs, function(doc) {
1111
if ( doc.docType === 'module' ) {
1212

@@ -21,7 +21,7 @@ module.exports = function processModuleDocs(log, ExportTreeVisitor, getJSDocComm
2121
_.forEach(visitor.exports, function(exportDoc) {
2222

2323
doc.exports.push(exportDoc);
24-
exportDocs.push(exportDoc);
24+
extraDocs.push(exportDoc);
2525
exportDoc.moduleDoc = doc;
2626

2727
if (exportDoc.comment) {
@@ -40,7 +40,7 @@ module.exports = function processModuleDocs(log, ExportTreeVisitor, getJSDocComm
4040
}
4141
});
4242

43-
return docs.concat(exportDocs);
43+
return docs.concat(extraDocs);
4444
}
4545
};
4646
};

‎docs/dgeni-package/processors/cloneExportedFromDocs.js‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
var _ = require('lodash');
2+
3+
module.exports = function cloneExportedFromDocs(modules, EXPORT_DOC_TYPES) {
4+
return {
5+
$runAfter: ['tags-parsed', 'attachModuleDocs'],
6+
$runBefore: ['computing-ids'],
7+
$process: function(docs) {
8+
9+
var extraPublicDocs = [];
10+
11+
_.forEach(docs, function(doc) {
12+
13+
if (EXPORT_DOC_TYPES.indexOf(doc.docType) === -1 || !doc.exportedAs) return;
14+
15+
_.forEach(doc.exportedAs, function(exportedAs) {
16+
var exportedAsModule = modules[exportedAs];
17+
18+
if (!exportedAsModule) {
19+
throw new Error('Missing module definition: "' + doc.exportedAs + '"\n' +
20+
'Referenced in "@exportedAs" tag on class: "' + doc.moduleDoc.id + '/' + doc.name + '"');
21+
} else {
22+
23+
// Add a clone of export to its "exportedAs" module
24+
var clonedDoc = _.clone(doc);
25+
clonedDoc.moduleDoc = exportedAsModule;
26+
exportedAsModule.exports.push(clonedDoc);
27+
extraPublicDocs.push(clonedDoc);
28+
}
29+
});
30+
});
31+
32+
docs = docs.concat(extraPublicDocs);
33+
34+
return docs;
35+
}
36+
};
37+
};

‎docs/dgeni-package/processors/createOverviewDump.js‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ var _ = require('lodash');
33
module.exports = function createOverviewDump() {
44

55
return {
6-
$runAfter: ['processModuleDocs', 'processClassDocs'],
6+
$runAfter: ['captureModuleExports', 'captureClassMembers'],
77
$runBefore: ['docs-processed'],
88
$process: function(docs) {
99
var overviewDoc = {

‎docs/dgeni-package/processors/generateDocsFromComments.js‎

Lines changed: 0 additions & 34 deletions
This file was deleted.

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

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
module.exports = {
2+
name: 'exportedAs',
3+
multi: true
4+
};

‎docs/dgeni-package/tag-defs/public.js‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
module.exports = {
2+
name: 'public',
3+
transforms: function(doc, tag) { return true; }
4+
};

0 commit comments

Comments
 (0)