From cf0968f98e844043a0f6c2548201f3c0dfd329a7 Mon Sep 17 00:00:00 2001 From: Pete Bacon Darwin Date: Thu, 14 Jun 2018 23:51:34 +0100 Subject: [PATCH] build(docs-infra): support hiding constructors of injectable classes (#24529) Classes that are injectable often have constructors that should not be called by the application developer. It is the responsibility of the injector to instantiate the class and the constructor often contains private implementation details that may need to change. This commit removes constructors from the docs for API items that are both: a) Marked with an injectable decorator (e.g. Injectable, Directive, Component, Pipe), and b) Have no constructor description This second rule allows the developer to override the removal if there is something useful to say about the constructor. Note that "normal" classes such as `angimations/HttpHeaders` do not have their constructor removed, despite (at this time) having no description. PR Close #24529 --- .../transforms/angular-api-package/index.js | 1 + .../removeInjectableConstructors.js | 18 ++++++ .../removeInjectableConstructors.spec.js | 58 +++++++++++++++++++ 3 files changed, 77 insertions(+) create mode 100644 aio/tools/transforms/angular-api-package/processors/removeInjectableConstructors.js create mode 100644 aio/tools/transforms/angular-api-package/processors/removeInjectableConstructors.spec.js diff --git a/aio/tools/transforms/angular-api-package/index.js b/aio/tools/transforms/angular-api-package/index.js index 5e0931a724694..d6838c892f8eb 100644 --- a/aio/tools/transforms/angular-api-package/index.js +++ b/aio/tools/transforms/angular-api-package/index.js @@ -32,6 +32,7 @@ module.exports = new Package('angular-api', [basePackage, typeScriptPackage]) .processor(require('./processors/computeSearchTitle')) .processor(require('./processors/simplifyMemberAnchors')) .processor(require('./processors/computeStability')) + .processor(require('./processors/removeInjectableConstructors')) /** * These are the API doc types that will be rendered to actual files. diff --git a/aio/tools/transforms/angular-api-package/processors/removeInjectableConstructors.js b/aio/tools/transforms/angular-api-package/processors/removeInjectableConstructors.js new file mode 100644 index 0000000000000..ea8daeb231e1c --- /dev/null +++ b/aio/tools/transforms/angular-api-package/processors/removeInjectableConstructors.js @@ -0,0 +1,18 @@ +module.exports = function removeInjectableConstructors() { + return { + $runAfter: ['processing-docs', 'splitDescription'], + $runBefore: ['docs-processed'], + injectableDecorators: ['Injectable', 'Directive', 'Component', 'Pipe', 'NgModule'], + $process(docs) { + docs.forEach(doc => { + if ( + doc.constructorDoc && + !doc.constructorDoc.shortDescription && + doc.decorators && + doc.decorators.some(decorator => this.injectableDecorators.indexOf(decorator.name) !== -1)) { + delete doc.constructorDoc; + } + }); + } + }; +}; diff --git a/aio/tools/transforms/angular-api-package/processors/removeInjectableConstructors.spec.js b/aio/tools/transforms/angular-api-package/processors/removeInjectableConstructors.spec.js new file mode 100644 index 0000000000000..d7372fa7c30a7 --- /dev/null +++ b/aio/tools/transforms/angular-api-package/processors/removeInjectableConstructors.spec.js @@ -0,0 +1,58 @@ +const processorFactory = require('./removeInjectableConstructors'); +const testPackage = require('../../helpers/test-package'); +const Dgeni = require('dgeni'); + +describe('removeInjectableConstructors processor', () => { + + it('should be available on the injector', () => { + const dgeni = new Dgeni([testPackage('angular-api-package')]); + const injector = dgeni.configureInjector(); + const processor = injector.get('removeInjectableConstructors'); + expect(processor.$process).toBeDefined(); + expect(processor.$runAfter).toEqual(['processing-docs', 'splitDescription']); + expect(processor.$runBefore).toEqual(['docs-processed']); + }); + + it('should remove undocumented constructors from docs that have an "Injectable" decorator on them', () => { + const processor = processorFactory(); + const docs = [ + { constructorDoc: {} }, + { constructorDoc: {}, decorators: [] }, + { constructorDoc: {}, decorators: [{ name: 'Injectable' }] }, + { constructorDoc: {}, decorators: [{ name: 'Component' }] }, + { constructorDoc: {}, decorators: [{ name: 'Directive' }] }, + { constructorDoc: {}, decorators: [{ name: 'Pipe' }] }, + { constructorDoc: {}, decorators: [{ name: 'Other' }, { name: 'Injectable' }] }, + { constructorDoc: {}, decorators: [{ name: 'Other' }] }, + + { constructorDoc: { shortDescription: 'Blah' } }, + { constructorDoc: { shortDescription: 'Blah' }, decorators: [] }, + { constructorDoc: { shortDescription: 'Blah' }, decorators: [{ name: 'Injectable' }] }, + { constructorDoc: { shortDescription: 'Blah' }, decorators: [{ name: 'Component' }] }, + { constructorDoc: { shortDescription: 'Blah' }, decorators: [{ name: 'Directive' }] }, + { constructorDoc: { shortDescription: 'Blah' }, decorators: [{ name: 'Pipe' }] }, + { constructorDoc: { shortDescription: 'Blah' }, decorators: [{ name: 'Other' }, { name: 'Injectable' }] }, + { constructorDoc: { shortDescription: 'Blah' }, decorators: [{ name: 'Other' }] }, + ]; + + processor.$process(docs); + + expect(docs[0].constructorDoc).toBeDefined(); + expect(docs[1].constructorDoc).toBeDefined(); + expect(docs[2].constructorDoc).toBeUndefined(); + expect(docs[3].constructorDoc).toBeUndefined(); + expect(docs[4].constructorDoc).toBeUndefined(); + expect(docs[5].constructorDoc).toBeUndefined(); + expect(docs[6].constructorDoc).toBeUndefined(); + expect(docs[7].constructorDoc).toBeDefined(); + + expect(docs[8].constructorDoc).toBeDefined(); + expect(docs[9].constructorDoc).toBeDefined(); + expect(docs[10].constructorDoc).toBeDefined(); + expect(docs[11].constructorDoc).toBeDefined(); + expect(docs[12].constructorDoc).toBeDefined(); + expect(docs[13].constructorDoc).toBeDefined(); + expect(docs[14].constructorDoc).toBeDefined(); + expect(docs[15].constructorDoc).toBeDefined(); + }); +});