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.

tools/api-builder/docs-package/index.js

@@ -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) {

tools/api-builder/docs-package/processors/addNotYetDocumentedProperty.js

@@ -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;
           });
         }
@@ -31,3 +31,7 @@ module.exports = function addNotYetDocumentedProperty(EXPORT_DOC_TYPES, log, cre
     }
   };
 };
+
+function notYetDocumented(doc) {
+  return !doc.noDescription && doc.description.trim().length == 0;
+}

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

@@ -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();
+  });
 });