From a98085e7ebacc382bc615950273a0c6d8a97cda5 Mon Sep 17 00:00:00 2001
From: Peter Bacon Darwin <pete@bacondarwin.com>
Date: Fri, 13 Nov 2015 12:45:00 +0000
Subject: [PATCH] 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       |  1 +
 .../processors/addNotYetDocumentedProperty.js | 12 ++++--
 .../addNotYetDocumentedProperty.spec.js       | 41 +++++++++++++++++++
 3 files changed, 50 insertions(+), 4 deletions(-)

diff --git a/tools/api-builder/docs-package/index.js b/tools/api-builder/docs-package/index.js
index a5fa802432..f219f15647 100644
--- a/tools/api-builder/docs-package/index.js
+++ b/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) {
diff --git a/tools/api-builder/docs-package/processors/addNotYetDocumentedProperty.js b/tools/api-builder/docs-package/processors/addNotYetDocumentedProperty.js
index fd3ba86446..67d7762a85 100644
--- a/tools/api-builder/docs-package/processors/addNotYetDocumentedProperty.js
+++ b/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;
           });
         }
@@ -30,4 +30,8 @@ module.exports = function addNotYetDocumentedProperty(EXPORT_DOC_TYPES, log, cre
       return docs;
     }
   };
-};
\ No newline at end of file
+};
+
+function notYetDocumented(doc) {
+  return !doc.noDescription && doc.description.trim().length == 0;
+}
\ 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
index beb6c71300..c7e4378ac0 100644
--- a/tools/api-builder/docs-package/processors/addNotYetDocumentedProperty.spec.js
+++ b/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();
+  });
 });
\ No newline at end of file