From dbc95b75af19affa6b1efc2962040c5833e498a7 Mon Sep 17 00:00:00 2001 From: Peter Bacon Darwin Date: Fri, 13 Nov 2015 16:34:57 +0000 Subject: [PATCH] api-builder: improve "not yet documented" handling * All export members are now tagged if they have no documentation. * All exports are tagged if they and their members have no documentation. * The templates for these docs display the words "Not Yet Documented" if they are tagged. * The build creates a warning for each export that is not documented * The build generates a new file, `public/docs/ts/latest/api/overview-dump.html`, which lists all the modules, exports and members highlighting those that are not documented. --- tools/api-builder/angular.io-package/index.js | 1 - .../templates/class.template.html | 9 +- .../templates/function.template.html | 5 +- .../templates/var.template.html | 2 +- tools/api-builder/docs-package/index.js | 1 + .../processors/addNotYetDocumentedProperty.js | 33 ++++++ .../addNotYetDocumentedProperty.spec.js | 104 ++++++++++++++++++ .../templates/lib/githubLinks.html | 6 +- .../templates/overview-dump.template.html | 53 +++++++-- .../processors/readTypeScriptModules.js | 11 -- 10 files changed, 198 insertions(+), 27 deletions(-) create mode 100644 tools/api-builder/docs-package/processors/addNotYetDocumentedProperty.js create mode 100644 tools/api-builder/docs-package/processors/addNotYetDocumentedProperty.spec.js diff --git a/tools/api-builder/angular.io-package/index.js b/tools/api-builder/angular.io-package/index.js index f58a64ef6d..d324975b65 100644 --- a/tools/api-builder/angular.io-package/index.js +++ b/tools/api-builder/angular.io-package/index.js @@ -58,7 +58,6 @@ module.exports = new Package('angular.io', [basePackage, targetPackage, cheatshe .config(function(readFilesProcessor, generateNavigationDoc, createOverviewDump) { // Clear out unwanted processors generateNavigationDoc.$enabled = false; - //createOverviewDump.$enabled = false; }) diff --git a/tools/api-builder/angular.io-package/templates/class.template.html b/tools/api-builder/angular.io-package/templates/class.template.html index 21c31c2826..ad04ec16ca 100644 --- a/tools/api-builder/angular.io-package/templates/class.template.html +++ b/tools/api-builder/angular.io-package/templates/class.template.html @@ -47,7 +47,11 @@ p.location-badge. code. {$ doc.constructorDoc.name $}{$ paramList(doc.constructorDoc.parameters) | indent(8, false) | trim $} :marked + {%- if doc.constructorDoc.notYetDocumented %} + *Not Yet Documented* + {% else %} {$ doc.constructorDoc.description | indentForMarkdown(6) | replace('## Example', '') | replace('# Example', '') | trimBlankLines $} + {% endif -%} {% endif -%} {%- for member in doc.members %}{% if not member.internal %} @@ -58,8 +62,11 @@ p.location-badge. {$ member.name $}{$ paramList(member.parameters) | indent(8, false) | trim $}{$ returnType(member.returnType) $} :marked + {%- if member.notYetDocumented %} + *Not Yet Documented* + {% else %} {$ member.description | indentForMarkdown(6) | replace('## Example', '') | replace('# Example', '') | trimBlankLines $} - + {% endif %} {% endif %}{% endfor %} {%- endif -%} diff --git a/tools/api-builder/angular.io-package/templates/function.template.html b/tools/api-builder/angular.io-package/templates/function.template.html index 8d10dfc67f..b59b1aef33 100644 --- a/tools/api-builder/angular.io-package/templates/function.template.html +++ b/tools/api-builder/angular.io-package/templates/function.template.html @@ -15,6 +15,9 @@ include ../../_util-fns defined in {$ githubViewLink(doc) $} :marked +{%- if doc.notYetDocumented %} + *Not Yet Documented* +{% else %} {$ doc.description | indentForMarkdown(4) | trimBlankLines $} - +{% endif %} {% endblock %} \ No newline at end of file diff --git a/tools/api-builder/angular.io-package/templates/var.template.html b/tools/api-builder/angular.io-package/templates/var.template.html index 639fa05e6b..69911f510c 100644 --- a/tools/api-builder/angular.io-package/templates/var.template.html +++ b/tools/api-builder/angular.io-package/templates/var.template.html @@ -16,7 +16,7 @@ include ../../_util-fns :marked {%- if doc.notYetDocumented %} - ### *Not Yet Documented* + *Not Yet Documented* {% else %} {$ doc.description | indentForMarkdown(4) | trimBlankLines $} {% endif -%} diff --git a/tools/api-builder/docs-package/index.js b/tools/api-builder/docs-package/index.js index 5239a3bdfb..a5fa802432 100644 --- a/tools/api-builder/docs-package/index.js +++ b/tools/api-builder/docs-package/index.js @@ -18,6 +18,7 @@ module.exports = new Package('angular-v2-docs', [jsdocPackage, nunjucksPackage, .processor(require('./processors/createOverviewDump')) .processor(require('./processors/checkUnbalancedBackTicks')) .processor(require('./processors/convertBackticksToCodeBlocks')) +.processor(require('./processors/addNotYetDocumentedProperty')) // Configure the log service .config(function(log) { diff --git a/tools/api-builder/docs-package/processors/addNotYetDocumentedProperty.js b/tools/api-builder/docs-package/processors/addNotYetDocumentedProperty.js new file mode 100644 index 0000000000..fd3ba86446 --- /dev/null +++ b/tools/api-builder/docs-package/processors/addNotYetDocumentedProperty.js @@ -0,0 +1,33 @@ +module.exports = function addNotYetDocumentedProperty(EXPORT_DOC_TYPES, 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 = doc.description.trim().length == 0; + + if (doc.constructorDoc) { + doc.constructorDoc.notYetDocumented = doc.constructorDoc.description.trim().length == 0; + doc.notYetDocumented = doc.notYetDocumented && doc.constructorDoc.notYetDocumented; + } + + if (doc.members) { + doc.members.forEach(function(member) { + member.notYetDocumented = member.description.trim().length == 0; + doc.notYetDocumented = doc.notYetDocumented && member.notYetDocumented; + }); + } + + if (doc.notYetDocumented) { + log.warn(createDocMessage("Not yet documented", doc)); + } + }); + + return docs; + } + }; +}; \ No newline at end of file diff --git a/tools/api-builder/docs-package/processors/addNotYetDocumentedProperty.spec.js b/tools/api-builder/docs-package/processors/addNotYetDocumentedProperty.spec.js new file mode 100644 index 0000000000..beb6c71300 --- /dev/null +++ b/tools/api-builder/docs-package/processors/addNotYetDocumentedProperty.spec.js @@ -0,0 +1,104 @@ +var mockPackage = require('../mocks/mockPackage'); +var Dgeni = require('dgeni'); + +describe('addNotYetDocumentedProperty', function() { + var dgeni, injector, processor, log; + + beforeEach(function() { + dgeni = new Dgeni([mockPackage()]); + injector = dgeni.configureInjector(); + processor = injector.get('addNotYetDocumentedProperty'); + log = injector.get('log'); + }); + + 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 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: '' } + ] + }, + ]; + + 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(); + }); +}); \ No newline at end of file diff --git a/tools/api-builder/docs-package/templates/lib/githubLinks.html b/tools/api-builder/docs-package/templates/lib/githubLinks.html index 574656542f..611ebdb13a 100644 --- a/tools/api-builder/docs-package/templates/lib/githubLinks.html +++ b/tools/api-builder/docs-package/templates/lib/githubLinks.html @@ -1,3 +1,7 @@ +{% macro githubHref(doc) -%} +https://github.com/{$ versionInfo.gitRepoInfo.owner $}/{$ versionInfo.gitRepoInfo.repo $}/tree/{$ versionInfo.currentVersion.isSnapshot and versionInfo.currentVersion.SHA or versionInfo.currentVersion.raw $}/modules/{$ doc.fileInfo.relativePath $}#L{$ doc.location.start.line+1 $}-L{$ doc.location.end.line+1 $} +{%- endmacro %} + {% macro githubViewLink(doc) -%} - {$ doc.fileInfo.relativePath $} (line {$ doc.location.start.line+1 $}) + {$ doc.fileInfo.relativePath $} (line {$ doc.location.start.line+1 $}) {%- endmacro -%} diff --git a/tools/api-builder/docs-package/templates/overview-dump.template.html b/tools/api-builder/docs-package/templates/overview-dump.template.html index 3f4ee1294f..535b57be45 100644 --- a/tools/api-builder/docs-package/templates/overview-dump.template.html +++ b/tools/api-builder/docs-package/templates/overview-dump.template.html @@ -1,38 +1,69 @@ +{% include "lib/githubLinks.html" -%} {% include "lib/paramList.html" -%} -

Modules

+

Module Overview

{% for module in doc.modules %} -

{$ module.id $} - {%- if module.public %} (public){% endif %}

+

+ {$ module.id $}{%- if module.public %} (public){% endif %} +

{% for export in module.exports %} -

{$ export.name $}

- - {%- if export.constructorDoc %} -

{$ doc.constructorDoc.name $}{$ paramList(doc.constructorDoc.params) $}

+

+ + {$ export.docType $} {$ export.name $} + +

+ {%- if export.constructorDoc %} +

+ + {$ export.constructorDoc.name $}{$ paramList(export.constructorDoc.params) $} + +

{% endif -%} {%- for member in export.members %} -

{$ member.name $}{$ paramList(member.params) $}

+

+ + {$ member.name $}{$ paramList(member.params) $} + +

{% endfor %} {% endfor %} diff --git a/tools/api-builder/typescript-package/processors/readTypeScriptModules.js b/tools/api-builder/typescript-package/processors/readTypeScriptModules.js index 00af64e3e8..e9eeef74db 100644 --- a/tools/api-builder/typescript-package/processors/readTypeScriptModules.js +++ b/tools/api-builder/typescript-package/processors/readTypeScriptModules.js @@ -126,17 +126,6 @@ module.exports = function readTypeScriptModules(tsParser, modules, getFileInfo, } } - // NotYetDocumented means that no top level comments and no member level comments - var notYetDocumented = exportDoc.content.trim().length == 0; - exportDoc.notYetDocumented = notYetDocumented && exportDoc.members.every(function(member) { - var content = member.content.trim(); - return content.length == 0; - }); - - if (exportDoc.notYetDocumented) { - log.warn(createDocMessage("Not yet documented", exportDoc)); - } - if (sortClassMembers) { exportDoc.members.sort(function(a, b) { if (a.name > b.name) return 1;