build(aio): add processor to migrate legacy tags `@whatItDoes` and `@howToUse` (#22401)

See https://github.com/angular/angular/issues/22135#issuecomment-367632372

PR Close #22401
This commit is contained in:
Pete Bacon Darwin 2018-02-23 13:47:26 +00:00 committed by Alex Eagle
parent e75f0cee18
commit b924ce3a62
3 changed files with 103 additions and 0 deletions

View File

@ -14,6 +14,7 @@ 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/convertPrivateClassesToInterfaces'))
.processor(require('./processors/generateApiListDoc'))
.processor(require('./processors/addNotYetDocumentedProperty'))

View File

@ -0,0 +1,36 @@
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');
}
}
};
};

View File

@ -0,0 +1,66 @@
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' }
]);
});
});