Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[api-documenter] Print out tag name for unknown block tags #1296

Merged
merged 6 commits into from
Jun 26, 2019
Merged

[api-documenter] Print out tag name for unknown block tags #1296

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
a6b3e8f
Print out tag name for unknown block tags
raymondfeng May 22, 2019
7bcee66
Merge branch 'master' into print-tag-name
halfnibble Jun 21, 2019
4082f53
Merge remote-tracking branch 'remotes/origin/master' into print-tag-name
octogonz Jun 23, 2019
9e29d90
Update change log to comply with our allowedEmailRegExps policy
octogonz Jun 23, 2019
df979b0
Fix a merge conflict from the previous PR
octogonz Jun 23, 2019
3dc2c76
Restore strict handling of unknown TSDoc nodes
octogonz Jun 23, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 8 additions & 2 deletions apps/api-documenter/src/markdown/MarkdownEmitter.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,8 @@ import {
DocSection,
DocNodeTransforms,
DocEscapedText,
DocErrorText
DocErrorText,
DocBlockTag
} from '@microsoft/tsdoc';
import { InternalError } from '@microsoft/node-core-library';

Expand Down Expand Up @@ -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);
console.warn('Unsupported element kind: ' + docNode.kind);
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@halfnibble This change was not safe in my opinion: If API Documenter does not recognize some part of the TSDoc syntax tree, that's a bug. We would want people to report an error, so we can determine a correct handling of that node.

Whereas if API Documenter silently ignored the unrecognized node, then it would be simply omitted from the output. It could be years before we eventually realized that we forgot to implement it. Note that it's okay to ignore an unsupported tag; here I'm referring to a generalized node in the tree.

This concern is particularly important since currently API Extractor / API Documenter are serving as the reference implementation of the TSDoc standard.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I pushed a fix.

}
}

Expand Down
20 changes: 19 additions & 1 deletion apps/api-documenter/src/markdown/test/CustomMarkdownEmitter.test.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,8 @@ import {
DocSoftBreak,
DocLinkTag,
DocHtmlStartTag,
DocHtmlEndTag
DocHtmlEndTag,
DocBlockTag
} from '@microsoft/tsdoc';

import { CustomDocNodes } from '../../nodes/CustomDocNodeKind';
Expand Down Expand Up @@ -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 },
Expand Down
4 changes: 4 additions & 0 deletions apps/api-documenter/src/markdown/test/__snapshots__/CustomMarkdownEmitter.test.ts.snap
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down
11 changes: 11 additions & 0 deletions common/changes/@microsoft/api-documenter/print-tag-name_2019-05-25-04-18.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
{
"changes": [
{
"packageName": "@microsoft/api-documenter",
"comment": "print out tag name for unknown block tags",
"type": "patch"
}
],
"packageName": "@microsoft/api-documenter",
"email": "[email protected]"
}