From 9364a14d36181f69a89ce60caaf4d11b9379493c Mon Sep 17 00:00:00 2001
From: George Kalpakas <kalpakas.g@gmail.com>
Date: Tue, 2 Jul 2019 01:02:56 +0300
Subject: [PATCH] fix(docs-infra): ignore `ng*Def` members in API docs (#31378)

`ng*Def` properties (such as `ngInjectorDef`) are not considered part of
the public API and should not appear in the API docs. This commit adds a
filter to remove these properties from the docs metadata.

PR Close #31378
---
 .../transforms/angular-api-package/index.js   |   7 ++
 .../processors/filterMembers.js               |  21 ++++
 .../processors/filterMembers.spec.js          | 102 ++++++++++++++++++
 3 files changed, 130 insertions(+)
 create mode 100644 aio/tools/transforms/angular-api-package/processors/filterMembers.js
 create mode 100644 aio/tools/transforms/angular-api-package/processors/filterMembers.spec.js

diff --git a/aio/tools/transforms/angular-api-package/index.js b/aio/tools/transforms/angular-api-package/index.js
index 93cbbf37c7..8a73fd552e 100644
--- a/aio/tools/transforms/angular-api-package/index.js
+++ b/aio/tools/transforms/angular-api-package/index.js
@@ -29,6 +29,7 @@ module.exports =
         .processor(require('./processors/processClassLikeMembers'))
         .processor(require('./processors/markBarredODocsAsPrivate'))
         .processor(require('./processors/filterPrivateDocs'))
+        .processor(require('./processors/filterMembers'))
         .processor(require('./processors/computeSearchTitle'))
         .processor(require('./processors/simplifyMemberAnchors'))
         .processor(require('./processors/computeStability'))
@@ -176,6 +177,12 @@ module.exports =
           filterContainedDocs.docTypes = API_CONTAINED_DOC_TYPES;
         })
 
+        .config(function(filterMembers) {
+          filterMembers.notAllowedPatterns.push(
+            /^ng[A-Z].*Def$/
+          );
+        })
+
 
         .config(function(computePathsProcessor, EXPORT_DOC_TYPES, generateApiListDoc) {
 
diff --git a/aio/tools/transforms/angular-api-package/processors/filterMembers.js b/aio/tools/transforms/angular-api-package/processors/filterMembers.js
new file mode 100644
index 0000000000..4409323d18
--- /dev/null
+++ b/aio/tools/transforms/angular-api-package/processors/filterMembers.js
@@ -0,0 +1,21 @@
+/**
+ * Filter out members (i.e. static and instance properties and methods) that match specific
+ * patterns. Patterns can be added (as `RegExp`s) to the `notAllowedPatterns` array.
+ *
+ * (By default, no members are excluded.)
+ */
+module.exports = function filterMembers() {
+  return {
+    $runAfter: ['processing-docs'],
+    $runBefore: ['docs-processed'],
+    notAllowedPatterns: [],
+    $process(docs) {
+      const isAllowed = ({name}) => !this.notAllowedPatterns.some(re => re.test(name));
+
+      docs.forEach(doc => {
+        if (doc.statics) doc.statics = doc.statics.filter(isAllowed);
+        if (doc.members) doc.members = doc.members.filter(isAllowed);
+      });
+    },
+  };
+};
diff --git a/aio/tools/transforms/angular-api-package/processors/filterMembers.spec.js b/aio/tools/transforms/angular-api-package/processors/filterMembers.spec.js
new file mode 100644
index 0000000000..0b6633aeb6
--- /dev/null
+++ b/aio/tools/transforms/angular-api-package/processors/filterMembers.spec.js
@@ -0,0 +1,102 @@
+const processorFactory = require('./filterMembers');
+const testPackage = require('../../helpers/test-package');
+const Dgeni = require('dgeni');
+
+describe('filterMembers processor', () => {
+
+  it('should be available on the injector', () => {
+    const dgeni = new Dgeni([testPackage('angular-api-package')]);
+    const injector = dgeni.configureInjector();
+    const processor = injector.get('filterMembers');
+    expect(processor.$process).toBeDefined();
+    expect(processor.$runAfter).toEqual(['processing-docs']);
+    expect(processor.$runBefore).toEqual(['docs-processed']);
+  });
+
+  it('should remove members that match one of the not allowed patterns', () => {
+    const processor = processorFactory();
+    processor.notAllowedPatterns = [/^foo/, /bar$/];
+    const docs = [
+      // Doc without members.
+      { },
+
+      // Doc with static members only.
+      {
+        statics: [
+          { name: 'fooStatic' },  // Will be removed.
+          { name: 'FOOStatic' },
+          { name: 'barStatic' },
+          { name: 'statiCbar' },  // Will be removed.
+        ],
+      },
+
+      // Doc with instance members only.
+      {
+        members: [
+          { name: 'fooInstance' },  // Will be removed.
+          { name: 'FOOInstance' },
+          { name: 'barInstance' },
+          { name: 'instancEbar' },  // Will be removed.
+        ],
+      },
+
+      // Doc with both static and instance members.
+      {
+        statics: [
+          { name: 'fooStatic' },  // Will be removed.
+          { name: 'FOOStatic' },
+          { name: 'barStatic' },
+          { name: 'statiCbar' },  // Will be removed.
+        ],
+        members: [
+          { name: 'fooInstance' },  // Will be removed.
+          { name: 'FOOInstance' },
+          { name: 'barInstance' },
+          { name: 'instancEbar' },  // Will be removed.
+        ],
+      },
+    ];
+
+    processor.$process(docs);
+
+    expect(docs).toEqual([
+      { },
+      {
+        statics: [ { name: 'FOOStatic' }, { name: 'barStatic' } ],
+      },
+      {
+        members: [ { name: 'FOOInstance' }, { name: 'barInstance' } ],
+      },
+      {
+        statics: [ { name: 'FOOStatic' }, { name: 'barStatic' } ],
+        members: [ { name: 'FOOInstance' }, { name: 'barInstance' } ],
+      },
+    ]);
+  });
+
+  it('should remove no members by default', () => {
+    const processor = processorFactory();
+    const expectedDocs = [
+      {
+        statics: [
+          { name: '' },
+          { name: 'foo' },
+          { name: '__bar' },
+          { name: 'ngBazDef' },
+        ],
+        members: [
+          { name: '' },
+          { name: 'foo' },
+          { name: '__bar' },
+          { name: 'ngBazDef' },
+        ],
+      },
+    ];
+    const actualDocs = JSON.parse(JSON.stringify(expectedDocs));
+
+    processor.$process(actualDocs);
+
+    expect(processor.notAllowedPatterns).toEqual([]);
+    expect(actualDocs).toEqual(expectedDocs);
+  });
+});