Merge pull request #1296 from raymondfeng/print-tag-name

[api-documenter] Print out tag name for unknown block tags
microsoft · Jun 26, 2019 · a44df82 · a44df82
2 parents cf40afd + 3dc2c76
commit a44df82
Show file tree

Hide file tree

Showing 5 changed files with 46 additions and 3 deletions.
diff --git a/apps/api-documenter/src/markdown/MarkdownEmitter.ts b/apps/api-documenter/src/markdown/MarkdownEmitter.ts
@@ -15,7 +15,8 @@ import {
   DocSection,
   DocNodeTransforms,
   DocEscapedText,
-  DocErrorText
+  DocErrorText,
+  DocBlockTag
 } from '@microsoft/tsdoc';
 import { InternalError } from '@microsoft/node-core-library';
 
@@ -191,8 +192,13 @@ export class MarkdownEmitter {
       case DocNodeKind.InlineTag: {
         break;
       }
+      case DocNodeKind.BlockTag: {
+        const tagNode: DocBlockTag = docNode as DocBlockTag;
+        console.warn('Unsupported block tag: ' + tagNode.tagName);
+        break;
+      }
       default:
-        throw new Error('Unsupported element kind: ' + docNode.kind);
+        throw new InternalError('Unsupported DocNodeKind kind: ' + docNode.kind);
     }
   }
 

diff --git a/apps/api-documenter/src/markdown/test/CustomMarkdownEmitter.test.ts b/apps/api-documenter/src/markdown/test/CustomMarkdownEmitter.test.ts
@@ -10,7 +10,8 @@ import {
   DocSoftBreak,
   DocLinkTag,
   DocHtmlStartTag,
-  DocHtmlEndTag
+  DocHtmlEndTag,
+  DocBlockTag
 } from '@microsoft/tsdoc';
 
 import { CustomDocNodes } from '../../nodes/CustomDocNodeKind';
@@ -131,6 +132,23 @@ test('render Markdown from TSDoc', () => {
     )
   ]);
 
+  output.appendNodes([
+    new DocHeading({ configuration, title: 'Unknown block tag' }),
+    new DocParagraph({ configuration },
+      [
+        new DocBlockTag({
+          configuration,
+          tagName: '@unknown'
+        }),
+        new DocEmphasisSpan({ configuration, bold: true },
+          [ new DocPlainText({ configuration, text: 'bold' }) ]
+        ),
+        new DocPlainText({ configuration, text: 'non-bold' }),
+        new DocPlainText({ configuration, text: 'more-non-bold' })
+      ]
+    )
+  ]);
+
   output.appendNodes([
     new DocHeading({ configuration, title: 'Bad characters' }),
     new DocParagraph({ configuration },

diff --git a/apps/api-documenter/src/markdown/test/__snapshots__/CustomMarkdownEmitter.test.ts.snap b/apps/api-documenter/src/markdown/test/__snapshots__/CustomMarkdownEmitter.test.ts.snap
@@ -28,6 +28,10 @@ This is a <b>bold</b> word.
 
 [a link](./index.md)<!-- --><b>bold</b>non-boldmore-non-bold
 
+## Unknown block tag
+
+<b>bold</b>non-boldmore-non-bold
+
 ## Bad characters
 
 <b>\\\\*one\\\\*two\\\\*</b><b>three\\\\*four</b>

diff --git a/common/changes/@microsoft/api-documenter/print-tag-name_2019-05-25-04-18.json b/common/changes/@microsoft/api-documenter/print-tag-name_2019-05-25-04-18.json
@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "packageName": "@microsoft/api-documenter",
+      "comment": "Avoid reporting a fatal error when an unknown block tag is encountered",
+      "type": "patch"
+    }
+  ],
+  "packageName": "@microsoft/api-documenter",
+  "email": "[email protected]"
+}
diff --git a/common/config/rush/nonbrowser-approved-packages.json b/common/config/rush/nonbrowser-approved-packages.json
@@ -190,6 +190,10 @@
       "name": "clean-css",
       "allowedCategories": [ "libraries" ]
     },
+    {
+      "name": "cli-table",
+      "allowedCategories": [ "libraries" ]
+    },
     {
       "name": "colors",
       "allowedCategories": [ "libraries", "tests" ]