honeymoose/angular-cn
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

build(docs-infra): remove legacy jsdoc tag processing (#26039)

Browse Source 
PR Close #26039
This commit is contained in:
Pete Bacon Darwin 2018-09-20 14:28:18 +01:00 committed by Kara Erickson
parent cf8ad24dcf
commit 3808416479
9 changed files with 10 additions and 134 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
aio/tools/transforms/angular-api-package/index.js vendored
View File

@ -14,7 +14,6 @@ const { API_SOURCE_PATH, API_TEMPLATES_PATH, requireFolder } = require('../confi
module.exports = new Package('angular-api', [basePackage, typeScriptPackage])
// Register the processors
.processor(require('./processors/migrateLegacyJSDocTags'))
.processor(require('./processors/splitDescription'))
.processor(require('./processors/convertPrivateClassesToInterfaces'))
.processor(require('./processors/generateApiListDoc'))

2
aio/tools/transforms/angular-api-package/processors/mergeDecoratorDocs.js vendored
View File

@ -42,7 +42,7 @@ const {mergeProperties} = require('../../helpers/utils');
*
* Finally we want to capture the documentation attached to the call signature interface of the
* associated decorator (1). We copy across the properties that we care about from this call
* signature (e.g. description, whatItDoes and howToUse).
* signature (e.g. `description` and `usageNotes`).
*/
module.exports = function mergeDecoratorDocs(log) {

36
aio/tools/transforms/angular-api-package/processors/migrateLegacyJSDocTags.js vendored
View File

@ -1,36 +0,0 @@
module.exports = function migrateLegacyJSDocTags(log, createDocMessage) {
return {
$runAfter: ['tags-extracted'],
$runBefore: ['processing-docs'],
$process(docs) {
let migrated = false;
docs.forEach(doc => {
if (doc.howToUse) {
if (doc.usageNotes) {
throw new Error(createDocMessage('`@usageNotes` and the deprecated `@howToUse` are not allowed on the same doc', doc));
}
log.debug(createDocMessage('Using deprecated `@howToUse` tag as though it was `@usageNotes` tag', doc));
doc.usageNotes = doc.howToUse;
doc.howToUse = null;
migrated = true;
}
if (doc.whatItDoes) {
log.debug(createDocMessage('Merging the content of `@whatItDoes` tag into the description.', doc));
if (doc.description) {
doc.description = `${doc.whatItDoes}\n\n${doc.description}`;
} else {
doc.description = doc.whatItDoes;
}
doc.whatItDoes = null;
migrated = true;
}
});
if (migrated) {
log.warn('Some deprecated tags were migrated.');
log.warn('This automatic handling will be removed in a future version of the doc generation.\n');
}
}
};
};

66
aio/tools/transforms/angular-api-package/processors/migrateLegacyJSDocTags.spec.js
View File

@ -1,66 +0,0 @@
const testPackage = require('../../helpers/test-package');
const processorFactory = require('./migrateLegacyJSDocTags');
const log = require('dgeni/lib/mocks/log')(false);
const createDocMessage = require('dgeni-packages/base/services/createDocMessage')();
const Dgeni = require('dgeni');
describe('migrateLegacyJSDocTags processor', () => {
it('should be available on the injector', () => {
const dgeni = new Dgeni([testPackage('angular-api-package')]);
const injector = dgeni.configureInjector();
const processor = injector.get('migrateLegacyJSDocTags');
expect(processor.$process).toBeDefined();
});
it('should run before the correct processor', () => {
const processor = processorFactory(log, createDocMessage);
expect(processor.$runBefore).toEqual(['processing-docs']);
});
it('should run after the correct processor', () => {
const processor = processorFactory(log, createDocMessage);
expect(processor.$runAfter).toEqual(['tags-extracted']);
});
it('should migrate `howToUse` property to `usageNotes` property', () => {
const processor = processorFactory(log, createDocMessage);
const docs = [
{ howToUse: 'this is how to use it' }
];
processor.$process(docs);
expect(docs[0].howToUse).toBe(null);
expect(docs[0].usageNotes).toEqual('this is how to use it');
});
it('should migrate `whatItDoes` property to the `description`', () => {
const processor = processorFactory(log, createDocMessage);
const docs = [
{ whatItDoes: 'what it does' },
{ whatItDoes: 'what it does', description: 'the description' },
{ description: 'the description' }
];
processor.$process(docs);
expect(docs[0].whatItDoes).toBe(null);
expect(docs[0].description).toEqual('what it does');
expect(docs[1].whatItDoes).toBe(null);
expect(docs[1].description).toEqual('what it does\n\nthe description');
expect(docs[2].whatItDoes).toBeUndefined();
expect(docs[2].description).toEqual('the description');
});
it('should ignore docs that have neither `howToUse` nor `whatItDoes` properties', () => {
const processor = processorFactory(log, createDocMessage);
const docs = [
{ },
{ description: 'the description' }
];
processor.$process(docs);
expect(docs).toEqual([
{ },
{ description: 'the description' }
]);
});
});

2
aio/tools/transforms/angular-api-package/processors/splitDescription.js vendored
View File

@ -5,7 +5,7 @@
*/
module.exports = function splitDescription() {
return {
$runAfter: ['tags-extracted', 'migrateLegacyJSDocTags'],
$runAfter: ['tags-extracted'],
$runBefore: ['processing-docs'],
docTypes: [],
$process(docs) {

2
aio/tools/transforms/angular-api-package/processors/splitDescription.spec.js
View File

@ -18,7 +18,7 @@ describe('splitDescription processor', () => {
it('should run after the correct processor', () => {
const processor = processorFactory();
expect(processor.$runAfter).toEqual(['tags-extracted', 'migrateLegacyJSDocTags']);
expect(processor.$runAfter).toEqual(['tags-extracted']);
});
it('should split the `description` property into the first paragraph and other paragraphs', () => {

11
aio/tools/transforms/angular-api-package/tag-defs/howToUse.js vendored
View File

@ -1,11 +0,0 @@
module.exports = function(log, createDocMessage) {
return {
name: 'howToUse',
deprecated: true,
transforms(doc, tag, value) {
log.warn(createDocMessage('Deprecated `@howToUse` tag found', doc));
log.warn('PLEASE FIX by renaming to `@usageNotes.');
return value;
}
};
};

11
aio/tools/transforms/angular-api-package/tag-defs/whatItDoes.js vendored
View File

@ -1,11 +0,0 @@
module.exports = function(log, createDocMessage) {
return {
name: 'whatItDoes',
deprecated: true,
transforms(doc, tag, value) {
log.warn(createDocMessage('Deprecated `@whatItDoes` tag found', doc));
log.warn('PLEASE FIX by adding the content of this tag as the first paragraph of the `@description` tag.');
return value;
}
};
};

9
aio/tools/transforms/templates/README.md
View File

@ -8,10 +8,9 @@ other templates. Templates can also import macros from other template files.
When extending a template, parent must declare blocks that can be overridden by the
child. The template extension hierarchy looks like this (with declared blocks in parentheses):
- layout/base.template.html (base)
- module.template.html
- layout/api-base.template.html (jumpNav, jumpNavLinks, whatItDoes, infoBar, securityConsiderations,
deprecationNotes, howToUse, details)
- layout/base.template.html (bread-crumbs, header, embedded contents and body)
- package.template.html
- export-base.template.html (short-description, security-notes, deprecation, overview, see-also, details, usageNotes)
- class.template.html
- directive.template.html
- enum.template.html
@ -21,8 +20,10 @@ child. The template extension hierarchy looks like this (with declared blocks in
- decorator.template.html
- function.template.html
- interface.template.html
- value-module.template.html
- type-alias.template.html
- pipe.template.html
- ngmodule.template.html
# Doc Properties