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

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.

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;
+        }
+      });
+    }
+  };
+};

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();
+  });
+});