feat: Support for @packageDocumentation

Closes #1080

Also removes the grunt task, we mention the third-party grunt plugin on the website, and the built in one has been broken since 2015 without anyone complaining.

package.json

@@ -78,8 +78,7 @@
   "keywords": [
     "typescript",
     "documentation",
-    "generator",
-    "gruntplugin"
+    "generator"
   ],
   "nyc": {
     "extension": [

src/lib/converter/factories/comment.ts

@@ -102,13 +102,26 @@ export function getRawComment(node: ts.Node): string | undefined {
     const comments = getJSDocCommentRanges(node, sourceFile.text);
     if (comments.length) {
         let comment: ts.CommentRange;
+        const explicitPackageComment = comments.find(comment =>
+            sourceFile.text.substring(comment.pos, comment.end).includes('@packageDocumentation'));
         if (node.kind === ts.SyntaxKind.SourceFile) {
-            if (comments.length === 1) {
+            if (explicitPackageComment) {
+                comment = explicitPackageComment;
+            } else if (comments.length > 1) {
+                // Legacy behavior, require more than one comment and use the first comment.
+                // TODO: GH#1083, follow deprecation process to phase this out.
+                comment = comments[0];
+            } else {
+                // Single comment that may be a license comment, bail.
                 return;
             }
-            comment = comments[0];
         } else {
             comment = comments[comments.length - 1];
+            // If a non-SourceFile node comment has this tag, it should not be attached to the node
+            // as it documents the whole file by convention.
+            if (sourceFile.text.substring(comment.pos, comment.end).includes('@packageDocumentation')) {
+                return;
+            }
         }
 
         return sourceFile.text.substring(comment.pos, comment.end);

src/lib/converter/plugins/CommentPlugin.ts

@@ -119,6 +119,10 @@ export class CommentPlugin extends ConverterComponent {
             }
             this.hidden.push(reflection);
         }
+
+        if (reflection.kindOf(ReflectionKind.ExternalModule)) {
+            CommentPlugin.removeTags(comment, 'packageDocumentation');
+        }
     }
 
     /**

src/test/converter/comment/comment.ts

@@ -1,3 +1,9 @@
+/**
+ * This is a module doc comment with legacy behavior.
+ */
+/** dummy comment */
+import './comment2';
+
 /**
  * A Comment for a class
  *

src/test/converter/comment/comment2.ts

@@ -0,0 +1,10 @@
+/**
+ * This is a module doc with the packageDocumentation tag to mark it as documentation
+ * for the whole module. It is *not* documentation for the `multiply` function.
+ *
+ * @packageDocumentation
+ */
+
+export function multiply(a: number, b: number) {
+    return a * b;
+}

src/test/converter/comment/specs.json

@@ -5,17 +5,20 @@
   "flags": {},
   "children": [
     {
-      "id": 1,
+      "id": 6,
       "name": "\"comment\"",
       "kind": 1,
       "kindString": "External module",
       "flags": {
         "isExported": true
       },
       "originalName": "%BASE%/comment/comment.ts",
+      "comment": {
+        "shortText": "This is a module doc comment with legacy behavior."
+      },
       "children": [
         {
-          "id": 2,
+          "id": 7,
           "name": "CommentedClass",
           "kind": 128,
           "kindString": "Class",
@@ -38,7 +41,7 @@
           },
           "children": [
             {
-              "id": 3,
+              "id": 8,
               "name": "prop",
               "kind": 1024,
               "kindString": "Property",
@@ -51,7 +54,7 @@
               "sources": [
                 {
                   "fileName": "comment.ts",
-                  "line": 28,
+                  "line": 34,
                   "character": 6
                 }
               ],
@@ -66,14 +69,14 @@
               "title": "Properties",
               "kind": 1024,
               "children": [
-                3
+                8
               ]
             }
           ],
           "sources": [
             {
               "fileName": "comment.ts",
-              "line": 24,
+              "line": 30,
               "character": 27
             }
           ]
@@ -84,7 +87,7 @@
           "title": "Classes",
           "kind": 128,
           "children": [
-            2
+            7
           ]
         }
       ],
@@ -95,13 +98,104 @@
           "character": 0
         }
       ]
+    },
+    {
+      "id": 1,
+      "name": "\"comment2\"",
+      "kind": 1,
+      "kindString": "External module",
+      "flags": {
+        "isExported": true
+      },
+      "originalName": "%BASE%/comment/comment2.ts",
+      "comment": {
+        "shortText": "This is a module doc with the packageDocumentation tag to mark it as documentation\nfor the whole module. It is *not* documentation for the `multiply` function.",
+        "tags": [
+          {
+            "tag": "packagedocumentation",
+            "text": "\n"
+          }
+        ]
+      },
+      "children": [
+        {
+          "id": 2,
+          "name": "multiply",
+          "kind": 64,
+          "kindString": "Function",
+          "flags": {
+            "isExported": true
+          },
+          "signatures": [
+            {
+              "id": 3,
+              "name": "multiply",
+              "kind": 4096,
+              "kindString": "Call signature",
+              "flags": {},
+              "parameters": [
+                {
+                  "id": 4,
+                  "name": "a",
+                  "kind": 32768,
+                  "kindString": "Parameter",
+                  "flags": {},
+                  "type": {
+                    "type": "intrinsic",
+                    "name": "number"
+                  }
+                },
+                {
+                  "id": 5,
+                  "name": "b",
+                  "kind": 32768,
+                  "kindString": "Parameter",
+                  "flags": {},
+                  "type": {
+                    "type": "intrinsic",
+                    "name": "number"
+                  }
+                }
+              ],
+              "type": {
+                "type": "intrinsic",
+                "name": "number"
+              }
+            }
+          ],
+          "sources": [
+            {
+              "fileName": "comment2.ts",
+              "line": 8,
+              "character": 24
+            }
+          ]
+        }
+      ],
+      "groups": [
+        {
+          "title": "Functions",
+          "kind": 64,
+          "children": [
+            2
+          ]
+        }
+      ],
+      "sources": [
+        {
+          "fileName": "comment2.ts",
+          "line": 1,
+          "character": 0
+        }
+      ]
     }
   ],
   "groups": [
     {
       "title": "External modules",
       "kind": 1,
       "children": [
+        6,
         1
       ]
     }