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
This commit is contained in:
Pete Bacon Darwin
Miško Hevery
parent
f256c02b5e
commit
19e6b8dad5
|
|
@ -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) {
|
||||
|
|
|
|||
|
|
@ -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;
|
||||
}
|
||||
|
|
|
|||
|
|
@ -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();
|
||||
});
|
||||
});
|
||||
|
|
|
|||
Loading…
Reference in New Issue