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

[raymondfeng]

We ran into various cases that tsdoc comments have unknown block tags, such as:

/**
 * @decorator A new tag
 * @return A bad tag
 */

Without this PR, api-documenter just aborts with Unsupported element kind: BlockTag. The error message is meaningless and it does not help fix the underlying issue.

I would also like to know what source TS file (line/column) has the invalid tag. Please let me know how to access such metadata so that I can improve this PR.

[octogonz]

api-documenter definitely should not be crashing for these inputs. We should fix that in this PR, at the very least.

But I'm not sure that the documentation tool render these blocks. For a commercial company, it can be embarrassing to have unprofessional get rendered on your public website. As a general policy, when we encounter an unrecognized TSDoc tag, it's safer to omit it than to render it.

Some specific thoughts on that:

• For trivial misspellings (@return instead of @returns), TSDoc is planning a "lax mode" that could support synonyms for tags. This is not much work, if someone wants it.

• For genuinely undefined tags, I'm thinking maybe they should get parsed as blocks, which would cause them to get omitted (since api-documenter ignores unrecognized block types). I'm proposing this change for the TSDoc parser in RFC: Support for custom TSDoc tags tsdoc#21 (comment) -- lemme know your thoughts on this design change.

• If your scenario is that you want to define custom tags for some special purpose, there's an existing issue [api-extractor] Support extensible AEDoc tags #519 that would allow them to be defined in api-extractor.json. We can prioritize it if you like. (The only reason it didn't get implemented yet is that nobody has asked.)

[raymondfeng]

@octogonz Thank you for the input.

In my case, the first step is to make sure unknown tags do NOT crash api-documenter. We should warn that such tags are ignored so that they can be fixed if it's there by mistake. Let me improve the PR to not throw an error.

[octogonz]

In my case, the first step is to make sure unknown tags do NOT crash api-documenter.

Agreed

We should warn that such tags are ignored so that they can be fixed if it's there by mistake.

Doesn't the tsdoc-undefined-tag warning catch it already?

[raymondfeng]

@octogonz Can you elaborate tsdoc-undefined-tag? Is it a configurable option?

[octogonz]

If you paste your comment into the TSDoc playground, you should see that warning being reported. And the default api-extractor.json should report it (messages.tsdocMessageReporting setting).

[halfnibble]

tsdoc may be showing a warning, but it looks like api-documenter throws an error by default.
This PR appears to address that issue and with the latest changes, it looks good to me.

[octogonz]

Agreed, looks like @raymondfeng already pushed a fix that addresses my concern above. I'll get this merged.

[octogonz]

@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.

[octogonz]

I pushed a fix.