Merge pull request #1632 from vidartf/throws

[api-extractor]: Add support for `@throws`
microsoft · Nov 24, 2019 · 248c0a8 · 248c0a8
2 parents 625c095 + c8011fe
commit 248c0a8
Show file tree

Hide file tree

Showing 7 changed files with 57 additions and 1 deletion.
diff --git a/apps/api-documenter/src/documenters/MarkdownDocumenter.ts b/apps/api-documenter/src/documenters/MarkdownDocumenter.ts
@@ -234,6 +234,7 @@ export class MarkdownDocumenter {
       case ApiItemKind.MethodSignature:
       case ApiItemKind.Function:
         this._writeParameterTables(output, apiItem as ApiParameterListMixin);
+        this._writeThrowsSection(output, apiItem);
         break;
       case ApiItemKind.Namespace:
         this._writePackageOrNamespaceTables(output, apiItem as ApiNamespace);
@@ -318,6 +319,27 @@ export class MarkdownDocumenter {
     }
   }
 
+  private _writeThrowsSection(output: DocSection, apiItem: ApiItem): void {
+    if (apiItem instanceof ApiDocumentedItem) {
+      const tsdocComment: DocComment | undefined = apiItem.tsdocComment;
+
+      if (tsdocComment) {
+        // Write the @throws blocks
+        const throwsBlocks: DocBlock[] = tsdocComment.customBlocks.filter(x => x.blockTag.tagNameWithUpperCase
+          === StandardTags.throws.tagNameWithUpperCase);
+
+        if (throwsBlocks.length > 0) {
+          const heading: string = 'Exceptions';
+          output.appendNode(new DocHeading({ configuration: this._tsdocConfiguration, title: heading }));
+
+          for (const throwsBlock of throwsBlocks) {
+            this._appendSection(output, throwsBlock.content);
+          }
+        }
+      }
+    }
+  }
+
   /**
    * GENERATE PAGE: MODEL
    */

diff --git a/apps/api-extractor-model/src/aedoc/AedocDefinitions.ts b/apps/api-extractor-model/src/aedoc/AedocDefinitions.ts
@@ -56,6 +56,7 @@ export class AedocDefinitions {
           StandardTags.remarks,
           StandardTags.returns,
           StandardTags.sealed,
+          StandardTags.throws,
           StandardTags.virtual
         ],
         true

diff --git a/build-tests/api-documenter-test/etc/api-documenter-test.api.json b/build-tests/api-documenter-test/etc/api-documenter-test.api.json
@@ -171,7 +171,7 @@
             {
               "kind": "Method",
               "canonicalReference": "api-documenter-test!DocClass1#exampleFunction:member(1)",
-              "docComment": "/**\n * This is an overloaded function.\n *\n * @param a - the first string\n *\n * @param b - the second string\n */\n",
+              "docComment": "/**\n * This is an overloaded function.\n *\n * @param a - the first string\n *\n * @param b - the second string\n *\n * @throws\n *\n * `Error` The first throws line\n *\n * @throws\n *\n * The second throws line\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",

diff --git a/...i-documenter-test/etc/markdown/api-documenter-test.docclass1.examplefunction.md b/...i-documenter-test/etc/markdown/api-documenter-test.docclass1.examplefunction.md
@@ -23,3 +23,9 @@ exampleFunction(a: string, b: string): string;
 
 `string`
 
+## Exceptions
+
+`Error` The first throws line
+
+The second throws line
+
diff --git a/build-tests/api-documenter-test/src/DocClass1.ts b/build-tests/api-documenter-test/src/DocClass1.ts
@@ -158,6 +158,11 @@ export class DocClass1 extends DocBaseClass implements IDocInterface1, IDocInter
    * This is an overloaded function.
    * @param a - the first string
    * @param b - the second string
+   *
+   * @throws `Error`
+   *  The first throws line
+   *
+   * @throws The second throws line
    */
   exampleFunction(a: string, b: string): string;
 

diff --git a/common/changes/@microsoft/api-documenter/throws_2019-11-19-15-40.json b/common/changes/@microsoft/api-documenter/throws_2019-11-19-15-40.json
@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "packageName": "@microsoft/api-documenter",
+      "comment": "Added support for `@throws`",
+      "type": "minor"
+    }
+  ],
+  "packageName": "@microsoft/api-documenter",
+  "email": "[email protected]"
+}
diff --git a/common/changes/@microsoft/api-extractor-model/throws_2019-11-19-15-40.json b/common/changes/@microsoft/api-extractor-model/throws_2019-11-19-15-40.json
@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "packageName": "@microsoft/api-extractor-model",
+      "comment": "Added support for `@throws`",
+      "type": "minor"
+    }
+  ],
+  "packageName": "@microsoft/api-extractor-model",
+  "email": "[email protected]"
+}