build(aio): fix addNotYetDocumentedProperty processor (#22770)

It was running too late and so was being confused by the
description being split into `shortDescription` and `description`
properties.

Closes #22748

PR Close #22770

aio/tools/transforms/angular-api-package/index.js

@@ -111,10 +111,11 @@ module.exports = new Package('angular-api', [basePackage, typeScriptPackage])
         parseTagsProcessor.tagDefinitions.concat(getInjectables(requireFolder(__dirname, './tag-defs')));
   })
 
-  .config(function(computeStability, splitDescription, EXPORT_DOC_TYPES, API_DOC_TYPES) {
+  .config(function(computeStability, splitDescription, addNotYetDocumentedProperty, EXPORT_DOC_TYPES, API_DOC_TYPES) {
     computeStability.docTypes = EXPORT_DOC_TYPES;
     // Only split the description on the API docs
     splitDescription.docTypes = API_DOC_TYPES;
+    addNotYetDocumentedProperty.docTypes = API_DOC_TYPES;
   })
 
   .config(function(computePathsProcessor, EXPORT_DOC_TYPES, generateApiListDoc) {

aio/tools/transforms/angular-api-package/processors/addNotYetDocumentedProperty.js

@@ -1,37 +1,19 @@
-module.exports = function addNotYetDocumentedProperty(EXPORT_DOC_TYPES, log, createDocMessage) {
+module.exports = function addNotYetDocumentedProperty(log, createDocMessage) {
   return {
-    $runAfter: ['tags-parsed'],
+    docTypes: [],
-    $runBefore: ['rendering-docs'],
+    $runAfter: ['tags-extracted'],
-    $process: function(docs) {
+    $runBefore: ['processing-docs', 'splitDescription'],
-      docs.forEach(function(doc) {
+    $process(docs) {
-
+      docs.forEach(doc => {
-        if (EXPORT_DOC_TYPES.indexOf(doc.docType) === -1) return;
+        if (
-
+          this.docTypes.indexOf(doc.docType) !== -1 &&
-        // NotYetDocumented means that no top level comments and no member level comments
+          !doc.noDescription &&
-        doc.notYetDocumented = notYetDocumented(doc);
+          (!doc.description || doc.description.trim().length === 0)
-
+        ) {
-        if (doc.constructorDoc) {
+          doc.notYetDocumented = true;
-          doc.constructorDoc.notYetDocumented = notYetDocumented(doc.constructorDoc);
-          doc.notYetDocumented = doc.notYetDocumented && doc.constructorDoc.notYetDocumented;
-        }
-
-        if (doc.members) {
-          doc.members.forEach(function(member) {
-            member.notYetDocumented = notYetDocumented(member);
-            doc.notYetDocumented = doc.notYetDocumented && member.notYetDocumented;
-          });
-        }
-
-        if (doc.notYetDocumented) {
           log.debug(createDocMessage('Not yet documented', doc));
         }
       });
-
-      return docs;
     }
   };
 };
-
-function notYetDocumented(doc) {
-  return !doc.noDescription && doc.description.trim().length == 0;
-}

aio/tools/transforms/angular-api-package/processors/addNotYetDocumentedProperty.spec.js

@@ -1,147 +1,60 @@
-var testPackage = require('../../helpers/test-package');
+const testPackage = require('../../helpers/test-package');
-var Dgeni = require('dgeni');
+const Dgeni = require('dgeni');
 
 describe('addNotYetDocumentedProperty', function() {
-  var dgeni, injector, processor;
+  let processor;
 
   beforeEach(function() {
-    dgeni = new Dgeni([testPackage('angular-api-package')]);
+    const dgeni = new Dgeni([testPackage('angular-api-package')]);
-    injector = dgeni.configureInjector();
+    const injector = dgeni.configureInjector();
     processor = injector.get('addNotYetDocumentedProperty');
+    processor.docTypes = ['test'];
+    processor.properties = ['description', 'name'];
   });
 
-  it('should mark export docs with no description as "not yet documented"', function() {
+  it('should run at the right time', () => {
-    var a, b, c, d, a1, b1, c1, d1;
+    expect(processor.$runAfter).toEqual(['tags-extracted']);
-    var docs = [
+    expect(processor.$runBefore).toEqual(['processing-docs', 'splitDescription']);
-      a = {id: 'a', docType: 'interface', description: 'some content'},
+  });
-      b = {id: 'b', docType: 'class', description: 'some content'},
+
-      c = {id: 'c', docType: 'var', description: 'some content'},
+  it('should mark docs with no `description` property as "not yet documented"', () => {
-      d = {id: 'd', docType: 'function', description: 'some content'},
+    const docs = [
-      a1 = {id: 'a1', docType: 'interface', description: ''},
+      {id: 'a', docType: 'test', description: 'some content' },
-      b1 = {id: 'b1', docType: 'class', description: ''},
+      {id: 'b', docType: 'test', description: '' },
-      c1 = {id: 'c1', docType: 'var', description: ''},
+      {id: 'c', docType: 'test' },
-      d1 = {id: 'd1', docType: 'function', description: ''}
     ];
 
     processor.$process(docs);
 
-    expect(a.notYetDocumented).toBeFalsy();
+    expect(docs[0].notYetDocumented).toBeFalsy();
-    expect(b.notYetDocumented).toBeFalsy();
+    expect(docs[1].notYetDocumented).toBeTruthy();
-    expect(c.notYetDocumented).toBeFalsy();
+    expect(docs[2].notYetDocumented).toBeTruthy();
-    expect(d.notYetDocumented).toBeFalsy();
-
-    expect(a1.notYetDocumented).toBeTruthy();
-    expect(b1.notYetDocumented).toBeTruthy();
-    expect(c1.notYetDocumented).toBeTruthy();
-    expect(d1.notYetDocumented).toBeTruthy();
   });
 
-  it('should mark member docs with no description as "not yet documented"', function() {
+  it('should ignore docs that do not match the specified doc types', () => {
-    var a, a1, a2, b, b1, b2, c, c1, c2;
+    const docs = [
-    var docs = [
+      {id: 'a', docType: 'other', description: '' },
-      a = {
+      {id: 'b', docType: 'other', shortDescription: '' },
-        id: 'a',
+      {id: 'c', docType: 'other' },
-        docType: 'interface',
-        description: 'some content',
-        members: [a1 = {id: 'a1', description: 'some content'}, a2 = {id: 'a2', description: ''}]
-      },
-      b = {
-        id: 'b',
-        docType: 'class',
-        description: '',
-        members: [b1 = {id: 'b1', description: 'some content'}, b2 = {id: 'b2', description: ''}]
-      },
-      c = {
-        id: 'c',
-        docType: 'class',
-        description: '',
-        members: [c1 = {id: 'c1', description: ''}, c2 = {id: 'c2', description: ''}]
-      },
     ];
 
     processor.$process(docs);
-
+    expect(docs[0].notYetDocumented).toBeFalsy();
-    expect(a.notYetDocumented).toBeFalsy();
+    expect(docs[1].notYetDocumented).toBeFalsy();
-    expect(b.notYetDocumented).toBeFalsy();
+    expect(docs[2].notYetDocumented).toBeFalsy();
-    expect(c.notYetDocumented).toBeTruthy();
-
-    expect(a1.notYetDocumented).toBeFalsy();
-    expect(a2.notYetDocumented).toBeTruthy();
-    expect(b1.notYetDocumented).toBeFalsy();
-    expect(b2.notYetDocumented).toBeTruthy();
-    expect(c1.notYetDocumented).toBeTruthy();
-    expect(c2.notYetDocumented).toBeTruthy();
-  });
-
-
-  it('should mark constructor doc with no description as "not yet documented"', function() {
-    var a, a1, b, b1;
-    var docs = [
-      a = {
-        id: 'a',
-        docType: 'interface',
-        description: '',
-        constructorDoc: a1 = {id: 'a1', description: 'some content'}
-      },
-      b = {
-        id: 'b',
-        docType: 'interface',
-        description: '',
-        constructorDoc: b1 = {id: 'b1', description: ''}
-      }
-    ];
-
-    processor.$process(docs);
-
-    expect(a.notYetDocumented).toBeFalsy();
-    expect(b.notYetDocumented).toBeTruthy();
-
-    expect(a1.notYetDocumented).toBeFalsy();
-    expect(b1.notYetDocumented).toBeTruthy();
   });
 
 
   it('should not mark documents explicitly tagged as `@noDescription`', function() {
-    var a, a1, a2, b, b1, b2, c, c1, c2;
+    const docs = [
-    var docs = [
+      {id: 'a', docType: 'other', description: '', noDescription: true },
-      a = {
+      {id: 'b', docType: 'other', shortDescription: '', noDescription: true },
-        id: 'a',
+      {id: 'c', docType: 'other', noDescription: true },
-        docType: 'interface',
-        description: 'some content',
-        members: [
-          a1 = {id: 'a1', description: 'some content'},
-          a2 = {id: 'a2', description: '', noDescription: true}
-        ]
-      },
-      b = {
-        id: 'b',
-        docType: 'class',
-        description: '',
-        members: [
-          b1 = {id: 'b1', description: 'some content'},
-          b2 = {id: 'b2', description: '', noDescription: true}
-        ]
-      },
-      c = {
-        id: 'c',
-        docType: 'class',
-        description: '',
-        noDescription: true,
-        members: [c1 = {id: 'c1', description: ''}, c2 = {id: 'c2', description: ''}]
-      },
     ];
 
     processor.$process(docs);
-
+    expect(docs[0].notYetDocumented).toBeFalsy();
-    expect(a.notYetDocumented).toBeFalsy();
+    expect(docs[1].notYetDocumented).toBeFalsy();
-    expect(b.notYetDocumented).toBeFalsy();
+    expect(docs[2].notYetDocumented).toBeFalsy();
-    expect(c.notYetDocumented).toBeFalsy();
-
-    expect(a1.notYetDocumented).toBeFalsy();
-    expect(a2.notYetDocumented).toBeFalsy();
-    expect(b1.notYetDocumented).toBeFalsy();
-    expect(b2.notYetDocumented).toBeFalsy();
-    expect(c1.notYetDocumented).toBeTruthy();
-    expect(c2.notYetDocumented).toBeTruthy();
   });
 });