From 48636f3e85cc3d6274d54da4262fa68998769987 Mon Sep 17 00:00:00 2001 From: Pete Bacon Darwin Date: Fri, 9 Mar 2018 08:26:11 +0000 Subject: [PATCH] build(aio): compute stability and deprecate `@stable` tag (#22674) Closes #22635 PR Close #22674 --- .../transforms/angular-api-package/index.js | 34 ++++++-- .../processors/computeStability.js | 18 ++++ .../processors/computeStability.spec.js | 82 +++++++++++++++++++ .../angular-api-package/tag-defs/stable.js | 11 ++- 4 files changed, 134 insertions(+), 11 deletions(-) create mode 100644 aio/tools/transforms/angular-api-package/processors/computeStability.js create mode 100644 aio/tools/transforms/angular-api-package/processors/computeStability.spec.js diff --git a/aio/tools/transforms/angular-api-package/index.js b/aio/tools/transforms/angular-api-package/index.js index 96a19da513..5ead537ca4 100644 --- a/aio/tools/transforms/angular-api-package/index.js +++ b/aio/tools/transforms/angular-api-package/index.js @@ -30,6 +30,24 @@ module.exports = new Package('angular-api', [basePackage, typeScriptPackage]) .processor(require('./processors/filterPrivateDocs')) .processor(require('./processors/computeSearchTitle')) .processor(require('./processors/simplifyMemberAnchors')) + .processor(require('./processors/computeStability')) + + /** + * These are the API doc types that will be rendered to actual files. + * This is a super set of the exported docs, since we convert some classes to + * more Angular specific API types, such as decorators and directives. + */ + .factory(function API_DOC_TYPES_TO_RENDER(EXPORT_DOC_TYPES) { + return EXPORT_DOC_TYPES.concat(['decorator', 'directive', 'pipe', 'module']); + }) + + /** + * These are the doc types that are API docs, including ones that will be merged into container docs, + * such as members and overloads. + */ + .factory(function API_DOC_TYPES(API_DOC_TYPES_TO_RENDER) { + return API_DOC_TYPES_TO_RENDER.concat(['member', 'function-overload']); + }) // Where do we get the source files? .config(function(readTypeScriptModules, readFilesProcessor, collectExamples, tsParser) { @@ -92,9 +110,10 @@ module.exports = new Package('angular-api', [basePackage, typeScriptPackage]) parseTagsProcessor.tagDefinitions.concat(getInjectables(requireFolder(__dirname, './tag-defs'))); }) - .config(function(splitDescription, EXPORT_DOC_TYPES) { + .config(function(computeStability, splitDescription, EXPORT_DOC_TYPES, API_DOC_TYPES) { + computeStability.docTypes = EXPORT_DOC_TYPES; // Only split the description on the API docs - splitDescription.docTypes = EXPORT_DOC_TYPES.concat(['member', 'function-overload']); + splitDescription.docTypes = API_DOC_TYPES; }) .config(function(computePathsProcessor, EXPORT_DOC_TYPES, generateApiListDoc) { @@ -124,12 +143,9 @@ module.exports = new Package('angular-api', [basePackage, typeScriptPackage]) }) - .config(function(convertToJsonProcessor, postProcessHtml, EXPORT_DOC_TYPES, autoLinkCode) { - const DOCS_TO_CONVERT = EXPORT_DOC_TYPES.concat([ - 'decorator', 'directive', 'pipe', 'module' - ]); - convertToJsonProcessor.docTypes = convertToJsonProcessor.docTypes.concat(DOCS_TO_CONVERT); - postProcessHtml.docTypes = convertToJsonProcessor.docTypes.concat(DOCS_TO_CONVERT); - autoLinkCode.docTypes = DOCS_TO_CONVERT.concat(['member', 'function-overload']); + .config(function(convertToJsonProcessor, postProcessHtml, API_DOC_TYPES_TO_RENDER, API_DOC_TYPES, autoLinkCode) { + convertToJsonProcessor.docTypes = convertToJsonProcessor.docTypes.concat(API_DOC_TYPES_TO_RENDER); + postProcessHtml.docTypes = convertToJsonProcessor.docTypes.concat(API_DOC_TYPES_TO_RENDER); + autoLinkCode.docTypes = API_DOC_TYPES; autoLinkCode.codeElements = ['code', 'code-example', 'code-pane']; }); diff --git a/aio/tools/transforms/angular-api-package/processors/computeStability.js b/aio/tools/transforms/angular-api-package/processors/computeStability.js new file mode 100644 index 0000000000..bcf1a2fb0d --- /dev/null +++ b/aio/tools/transforms/angular-api-package/processors/computeStability.js @@ -0,0 +1,18 @@ +module.exports = function computeStability(log, createDocMessage) { + return { + docTypes: [], + $runAfter: ['tags-extracted'], + $runBefore: ['rendering-docs'], + $process(docs) { + docs.forEach(doc => { + if (this.docTypes.indexOf(doc.docType) !== -1 && + doc.experimental === undefined && + doc.deprecated === undefined && + doc.stable === undefined) { + log.debug(createDocMessage('Adding stable property', doc)); + doc.stable = true; + } + }); + } + }; +}; diff --git a/aio/tools/transforms/angular-api-package/processors/computeStability.spec.js b/aio/tools/transforms/angular-api-package/processors/computeStability.spec.js new file mode 100644 index 0000000000..e1203c8d83 --- /dev/null +++ b/aio/tools/transforms/angular-api-package/processors/computeStability.spec.js @@ -0,0 +1,82 @@ +const log = require('dgeni/lib/mocks/log')(false); +const createDocMessage = require('dgeni-packages/base/services/createDocMessage')(); +const computeStability = require('./computeStability')(log, createDocMessage); +const testPackage = require('../../helpers/test-package'); +const Dgeni = require('dgeni'); + +describe('computeStability processor', () => { + + it('should be available on the injector', () => { + const dgeni = new Dgeni([testPackage('angular-api-package')]); + const injector = dgeni.configureInjector(); + const processor = injector.get('computeStability'); + expect(processor.$process).toBeDefined(); + }); + + it('should run before the correct processor', () => { + expect(computeStability.$runBefore).toEqual(['rendering-docs']); + }); + + it('should run after the correct processor', () => { + expect(computeStability.$runAfter).toEqual(['tags-extracted']); + }); + + it('should compute stability based on the existence of experimental and deprecated tags', () => { + computeStability.docTypes = ['test']; + const docs = [ + { docType: 'test' }, + { docType: 'test', experimental: undefined }, + { docType: 'test', experimental: true }, + { docType: 'test', experimental: '' }, + { docType: 'test', deprecated: undefined }, + { docType: 'test', deprecated: true }, + { docType: 'test', deprecated: '' }, + { docType: 'test', experimental: true, deprecated: true }, + ]; + computeStability.$process(docs); + expect(docs.map(doc => doc.stable)).toEqual([ + true, + true, + undefined, + undefined, + true, + undefined, + undefined, + undefined + ]); + }); + + it('should ignore docs that are not in the docTypes list', () => { + computeStability.docTypes = ['test1', 'test2']; + const docs = [ + { docType: 'test1' }, + { docType: 'test2' }, + { docType: 'test3' }, + { docType: 'test4' }, + ]; + computeStability.$process(docs); + expect(docs.map(doc => doc.stable)).toEqual([ + true, + true, + undefined, + undefined + ]); + }); + + it('should not ignore docs where `stable` has already been defined', () => { + computeStability.docTypes = ['test']; + const docs = [ + { docType: 'test' }, + { docType: 'test', stable: true }, + { docType: 'test', stable: '' }, + { docType: 'test', stable: undefined }, + ]; + computeStability.$process(docs); + expect(docs.map(doc => doc.stable)).toEqual([ + true, + true, + '', + true + ]); + }); +}); diff --git a/aio/tools/transforms/angular-api-package/tag-defs/stable.js b/aio/tools/transforms/angular-api-package/tag-defs/stable.js index 08c5077d74..7146ebdcb4 100644 --- a/aio/tools/transforms/angular-api-package/tag-defs/stable.js +++ b/aio/tools/transforms/angular-api-package/tag-defs/stable.js @@ -1,3 +1,10 @@ -module.exports = function() { - return {name: 'stable'}; +module.exports = function(log, createDocMessage) { + return { + name: 'stable', + transforms(doc, tag, value) { + log.warn(createDocMessage('Deprecated `@stable` tag found', doc)); + log.warn('PLEASE REMOVE - its value is now computed.'); + return value; + } + }; };