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.
2015-11-13 16:34:57 +00:00 · 2015-11-13 16:34:57 +00:00 · dbc95b75af
parent 489ffc9f97
commit dbc95b75af
10 changed files with 198 additions and 27 deletions
--- 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;
 })


--- a/tools/api-builder/angular.io-package/templates/class.template.html
+++ b/tools/api-builder/angular.io-package/templates/class.template.html
@ -47,8 +47,12 @@ 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 %}
  .l-sub-section
@ -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 -%}

--- 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 %}
--- 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 -%}
--- 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) {
--- a/tools/api-builder/docs-package/processors/addNotYetDocumentedProperty.js
+++ 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;
+    }
+  };
+};
--- a/tools/api-builder/docs-package/processors/addNotYetDocumentedProperty.spec.js
+++ 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();
+  });
+});
--- 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) -%}
-  <a href="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 $}">{$ doc.fileInfo.relativePath $} (line {$ doc.location.start.line+1 $})</a>
+  <a href="{$ githubHref(doc) $}">{$ doc.fileInfo.relativePath $} (line {$ doc.location.start.line+1 $})</a>
 {%- endmacro -%}
--- 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" -%}
 <!DOCTYPE html>
 <html>
 <head>
  <title></title>
  <style>
+    body {
+      max-width: 1000px;
+    }
    h2 {
-      padding-left: 20px;
+      margin-top: 20px;
+      margin-bottom: 0;
+      border-bottom: solid 1px black;
    }
    h3 {
-      padding-left: 50px;
+      margin-top: 10px;
+      margin-bottom: 0;
+      padding-left: 20px;
    }
    h4 {
-      padding-left: 60px;
+      padding-left: 30px;
+      margin: 0;
+    }
+    .not-documented::after {
+      content: "(not documented)";
+      font-size: small;
+      font-style: italic;
+      color: red;
+    }
+    a {
+      color: black;
+      text-decoration: none;
    }
  </style>
 </head>
 <body>


-<h1>Modules</h1>
+<h1>Module Overview</h1>

 {% for module in doc.modules %}

-<h2>{$ module.id $}
-    {%- if module.public %} (public){% endif %}</h2>
+<h2>
+  <code>{$ module.id $}{%- if module.public %} (public){% endif %}</code>
+</h2>

  {% for export in module.exports %}
-  <h3>{$ export.name $}</h3>
-
+  <h3 {% if export.notYetDocumented %}class="not-documented"{% endif %}>
+    <a href="{$ githubHref(export) $}">
+    <code>{$ export.docType $} {$ export.name $}</code>
+    </a>
+  </h3>
      {%- if export.constructorDoc %}
-      <h4>{$ doc.constructorDoc.name $}{$ paramList(doc.constructorDoc.params) $}</h4>
+      <h4  {% if export.constructorDoc.notYetDocumented %}class="not-documented"{% endif %}>
+        <a href="{$ githubHref(export.constructorDoc) $}">
+        <code>{$ export.constructorDoc.name $}{$ paramList(export.constructorDoc.params) $}</code>
+        </a>
+      </h4>
    {% endif -%}
    {%- for member in export.members %}
-      <h4>{$ member.name $}{$ paramList(member.params) $}</h4>
+      <h4 {% if member.notYetDocumented %}class="not-documented"{% endif %}>
+        <a href="{$ githubHref(member) $}">
+        <code>{$ member.name $}{$ paramList(member.params) $}</code>
+        </a>
+      </h4>
    {% endfor %}

  {% endfor %}
--- 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;