Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

build(aio): fix addNotYetDocumentedProperty processor #22770

Closed
wants to merge 1 commit into from
Closed

build(aio): fix addNotYetDocumentedProperty processor #22770

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
3 changes: 2 additions & 1 deletion aio/tools/transforms/angular-api-package/index.js
View file
Open in desktop
Expand Up @@ -110,10 +110,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) {
Expand Down
42 changes: 12 additions & 30 deletions aio/tools/transforms/angular-api-package/processors/addNotYetDocumentedProperty.js
View file
Open in desktop
@@ -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;
}
153 changes: 33 additions & 120 deletions aio/tools/transforms/angular-api-package/processors/addNotYetDocumentedProperty.spec.js
View file
Open in desktop
@@ -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: ''}
];

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();
it('should run at the right time', () => {
expect(processor.$runAfter).toEqual(['tags-extracted']);
expect(processor.$runBefore).toEqual(['processing-docs', 'splitDescription']);
});

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 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).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();
expect(docs[0].notYetDocumented).toBeFalsy();
expect(docs[1].notYetDocumented).toBeTruthy();
expect(docs[2].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: ''}
}
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).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();
});
});