iSharkFly-Docs
/
angular-docs-cn
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

api-builder: allow descriptions to be empty via the `@noDescription` tag 

If a document description is empty then it is marked with the `notYetDocumented`
property. This change allows developers to tag a code item (export, member, etc)
as explicitly not needing a description.
This commit is contained in:
Peter Bacon Darwin 2015-11-13 12:45:00 +00:00
parent 21feaf499f
commit a98085e7eb
3 changed files with 50 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
tools/api-builder/docs-package/index.js
View File

@ -28,6 +28,7 @@ module.exports = new Package('angular-v2-docs', [jsdocPackage, nunjucksPackage,
.config(function(parseTagsProcessor) {
parseTagsProcessor.tagDefinitions.push({ name: 'internal', transforms: function() { return true; } });
parseTagsProcessor.tagDefinitions.push({ name: 'syntax' });
parseTagsProcessor.tagDefinitions.push({ name: 'noDescription', transforms: function() { return true; } });
})
.config(function(renderDocsProcessor, versionInfo) {

12
tools/api-builder/docs-package/processors/addNotYetDocumentedProperty.js
View File

@ -8,16 +8,16 @@ module.exports = function addNotYetDocumentedProperty(EXPORT_DOC_TYPES, log, cre
if (EXPORT_DOC_TYPES.indexOf(doc.docType) === -1) return;
// NotYetDocumented means that no top level comments and no member level comments
doc.notYetDocumented = doc.description.trim().length == 0;
doc.notYetDocumented = notYetDocumented(doc);
if (doc.constructorDoc) {
doc.constructorDoc.notYetDocumented = doc.constructorDoc.description.trim().length == 0;
doc.constructorDoc.notYetDocumented = notYetDocumented(doc.constructorDoc);
doc.notYetDocumented = doc.notYetDocumented && doc.constructorDoc.notYetDocumented;
}
if (doc.members) {
doc.members.forEach(function(member) {
member.notYetDocumented = member.description.trim().length == 0;
member.notYetDocumented = notYetDocumented(member);
doc.notYetDocumented = doc.notYetDocumented && member.notYetDocumented;
});
}
@ -30,4 +30,8 @@ module.exports = function addNotYetDocumentedProperty(EXPORT_DOC_TYPES, log, cre
return docs;
}
};
};
};
function notYetDocumented(doc) {
return !doc.noDescription && doc.description.trim().length == 0;
}

41
tools/api-builder/docs-package/processors/addNotYetDocumentedProperty.spec.js
View File

@ -101,4 +101,45 @@ describe('addNotYetDocumentedProperty', function() {
expect(a1.notYetDocumented).toBeFalsy();
expect(b1.notYetDocumented).toBeTruthy();
});
it('should not mark documents explicity 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: '' }
]
},
];
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();
});
});