From 19e6b8dad57ff8a471824b91a0740b538d77b389 Mon Sep 17 00:00:00 2001 From: Pete Bacon Darwin Date: Wed, 14 Mar 2018 19:15:11 +0000 Subject: [PATCH] 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 --- .../transforms/angular-api-package/index.js | 3 +- .../processors/addNotYetDocumentedProperty.js | 42 ++--- .../addNotYetDocumentedProperty.spec.js | 157 ++++-------------- 3 files changed, 49 insertions(+), 153 deletions(-) diff --git a/aio/tools/transforms/angular-api-package/index.js b/aio/tools/transforms/angular-api-package/index.js index 1c26fec515..49bc40905a 100644 --- a/aio/tools/transforms/angular-api-package/index.js +++ b/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) { diff --git a/aio/tools/transforms/angular-api-package/processors/addNotYetDocumentedProperty.js b/aio/tools/transforms/angular-api-package/processors/addNotYetDocumentedProperty.js index f6ab7ae7c3..d9b69709f7 100644 --- a/aio/tools/transforms/angular-api-package/processors/addNotYetDocumentedProperty.js +++ b/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'], - $runBefore: ['rendering-docs'], - $process: function(docs) { - docs.forEach(function(doc) { - - if (EXPORT_DOC_TYPES.indexOf(doc.docType) === -1) return; - - // NotYetDocumented means that no top level comments and no member level comments - doc.notYetDocumented = notYetDocumented(doc); - - if (doc.constructorDoc) { - 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) { + docTypes: [], + $runAfter: ['tags-extracted'], + $runBefore: ['processing-docs', 'splitDescription'], + $process(docs) { + docs.forEach(doc => { + if ( + this.docTypes.indexOf(doc.docType) !== -1 && + !doc.noDescription && + (!doc.description || doc.description.trim().length === 0) + ) { + doc.notYetDocumented = true; log.debug(createDocMessage('Not yet documented', doc)); } }); - - return docs; } }; }; - -function notYetDocumented(doc) { - return !doc.noDescription && doc.description.trim().length == 0; -} diff --git a/aio/tools/transforms/angular-api-package/processors/addNotYetDocumentedProperty.spec.js b/aio/tools/transforms/angular-api-package/processors/addNotYetDocumentedProperty.spec.js index d6c9dbcf18..e8037165f3 100644 --- a/aio/tools/transforms/angular-api-package/processors/addNotYetDocumentedProperty.spec.js +++ b/aio/tools/transforms/angular-api-package/processors/addNotYetDocumentedProperty.spec.js @@ -1,147 +1,60 @@ -var testPackage = require('../../helpers/test-package'); -var Dgeni = require('dgeni'); +const testPackage = require('../../helpers/test-package'); +const Dgeni = require('dgeni'); describe('addNotYetDocumentedProperty', function() { - var dgeni, injector, processor; + let processor; beforeEach(function() { - dgeni = new Dgeni([testPackage('angular-api-package')]); - injector = dgeni.configureInjector(); + const dgeni = new Dgeni([testPackage('angular-api-package')]); + 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() { - var a, b, c, d, a1, b1, c1, d1; - var docs = [ - a = {id: 'a', docType: 'interface', description: 'some content'}, - b = {id: 'b', docType: 'class', description: 'some content'}, - c = {id: 'c', docType: 'var', description: 'some content'}, - d = {id: 'd', docType: 'function', description: 'some content'}, - a1 = {id: 'a1', docType: 'interface', description: ''}, - b1 = {id: 'b1', docType: 'class', description: ''}, - c1 = {id: 'c1', docType: 'var', description: ''}, - d1 = {id: 'd1', docType: 'function', description: ''} + it('should run at the right time', () => { + expect(processor.$runAfter).toEqual(['tags-extracted']); + expect(processor.$runBefore).toEqual(['processing-docs', 'splitDescription']); + }); + + it('should mark docs with no `description` property as "not yet documented"', () => { + const docs = [ + {id: 'a', docType: 'test', description: 'some content' }, + {id: 'b', docType: 'test', description: '' }, + {id: 'c', docType: 'test' }, ]; processor.$process(docs); - expect(a.notYetDocumented).toBeFalsy(); - expect(b.notYetDocumented).toBeFalsy(); - expect(c.notYetDocumented).toBeFalsy(); - expect(d.notYetDocumented).toBeFalsy(); - - expect(a1.notYetDocumented).toBeTruthy(); - expect(b1.notYetDocumented).toBeTruthy(); - expect(c1.notYetDocumented).toBeTruthy(); - expect(d1.notYetDocumented).toBeTruthy(); + expect(docs[0].notYetDocumented).toBeFalsy(); + expect(docs[1].notYetDocumented).toBeTruthy(); + expect(docs[2].notYetDocumented).toBeTruthy(); }); - it('should mark member docs with no description as "not yet documented"', function() { - var a, a1, a2, b, b1, b2, c, c1, c2; - var docs = [ - a = { - id: 'a', - 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: ''}] - }, + it('should ignore docs that do not match the specified doc types', () => { + const docs = [ + {id: 'a', docType: 'other', description: '' }, + {id: 'b', docType: 'other', shortDescription: '' }, + {id: 'c', docType: 'other' }, ]; processor.$process(docs); - - expect(a.notYetDocumented).toBeFalsy(); - expect(b.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(); + expect(docs[0].notYetDocumented).toBeFalsy(); + expect(docs[1].notYetDocumented).toBeFalsy(); + expect(docs[2].notYetDocumented).toBeFalsy(); }); it('should not mark documents explicitly tagged as `@noDescription`', function() { - var a, a1, a2, b, b1, b2, c, c1, c2; - var docs = [ - a = { - id: 'a', - 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: ''}] - }, + const docs = [ + {id: 'a', docType: 'other', description: '', noDescription: true }, + {id: 'b', docType: 'other', shortDescription: '', noDescription: true }, + {id: 'c', docType: 'other', noDescription: true }, ]; processor.$process(docs); - - expect(a.notYetDocumented).toBeFalsy(); - expect(b.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(); + expect(docs[0].notYetDocumented).toBeFalsy(); + expect(docs[1].notYetDocumented).toBeFalsy(); + expect(docs[2].notYetDocumented).toBeFalsy(); }); });