[api-extractor] Support extensible AEDoc tags

[tomdale]

First, let me just say I've really been enjoying using api-extractor. I was struggling for days getting anything to work in TypeDoc, but got a proof of concept working with api-extractor in less than an hour.

I'm currently playing around with generating API documentation for Glimmer.js and piping the JSON into a Glimmer app that renders it:

One limitation I've run into is that it's not possible to extend AEDoc annotations with additional metadata. For example, we want to be able to group methods and properties by "topic" instead of one big list per class. I'd like to be able to do something like @topic Lifecycle Hooks to indicate which topic a class or interface member belongs to.

I'm sympathetic to the design goal of precise parsing, but would you be open to some sort of configuration that whitelists additional annotations in comments, which would get included in JSON output?

[octogonz]

Yes, several others have asked about this. We are working on evolving AEDoc into something more formal and extensible, and ideally standardized across other tools. If you like I can include you for comments as soon as we have an initial draft.

[octogonz]

This requirement should be mostly addressed once we finish integrating https://github.com/Microsoft/tsdoc into API Extractor. It's almost ready.

[zombieyang]

@pgonzal does it finish? can we make some extensions now?

[octogonz]

Yes, all that is missing is a setting to register the custom tags so that API Extractor doesn't report them as errors.

Can you give some more details for how you will use the custom tags? Will you modify api-documenter to process them somehow? Or will you have a different tool that parses TypeScript source files (or maybe reads the .api.json files)?

[zombieyang]

Thank you for your reply.

I think I do have to modify api-documenter or the tools which can parse markdown to website.

We're developing a game engine using Entity-Component-System architecture. So sometimes we have to mark which System is the class is belonged to. So we may need to register a @system tag.

Or sometimes the doc website page path is not associated to the file path. We need to register a @web-path tag. so that the markdown parsing tools could generate the website according to this property.

[octogonz]

That makes sense! I'll see if I can get this implemented for you in the next week. There's very little work required at this point.

[octogonz]

BTW after PR #1120 is merged, one possible workaround would be to suppress the tsdoc-unsupported-tag or tsdoc-undefined-tag messages from the TSDoc parser.

[octogonz]

@natalieethell also needed this to support custom TSDoc tags for categorizing the office-ui-fabric-react docs

[halfnibble]

@octogonz @natalieethell @tomdale and all interested parties, now that PR #1210 is merged, is the workaround sufficient, or are we still missing something?

[octogonz]

@halfnibble we do still need to implement this.

It's possible to work around the issue by suppressing tsdoc-undefined-tag, but that has the downside of disabling error checking for all tags. For example, the workaround would cause a misspelled tag like @remarkss to get ignored, rather than reporting a warning.

The right solution is to introduce new settings in api-exctractor.json that allow people to define their custom tags. These definitions would supplement the built-in definitions from AedocDefinitions.ts.

[jeremyben]

@octogonz I was looking at a way to pass my own custom tags to api-extractor, both declaratively and programmatically, but I couldn't find it ! To me, it's important that we could "feed" the tsdoc parser via api-extractor so we can have the best of both tools.

Could you prioritize this feature or would you like a PR, and if so, could you point me in the right direction to implement this (which packages, files to look at) ?

[ecraig12345]

I took a stab at implementing this in #1628.

[nicholasrice]

Looking for this exact feature! I am looking to document various Web Component features such as:

• CSS Parts
• slots
• custom events
• custom element names
• HTML attribute names
• document focus delegation

It looks like @ecraig12345 took a great stab at this, but the solution needs to be re-worked slightly to pull configuration from https://www.npmjs.com/package/@microsoft/tsdoc-config - is that right? If so, I'd be happy make some adjustments to #1628 to get this rolling again.

[octogonz]

@nicholasrice that would be great! This is a cool feature, and we already made a lot of progress with it, so it would be awesome to finally finish it.

If memory serves, we left off with the problem that API Extractor is building its TSDoc configuration programmatically at runtime:

https://github.com/microsoft/rushstack/blob/a30cdf5b3caed87c63ee55f2c91dc1409fa7d29b/apps/api-extractor-model/src/aedoc/AedocDefinitions.ts#L25-L35

This configuration is invisible to other tools like eslint-plugin-tsdoc. We need to fix that.

There's at least a few missing pieces:

1. Move API Extractor's configuration into a base tsdoc-aedoc.json file (instead of constructing it programmatically)
2. Allow projects to include a custom tsdoc.json file (which should extend tsdoc-aedoc.json using "extends")
3. If the custom file is present, API Extractor should use that instead of loading tsdoc-aedoc.json directly

Notes:

• This would enable eslint-plugin-tsdoc to correctly validate custom tags and AEDoc tags more strictly
• Technically the TSDoc configuration should be constructed separately for each NPM package being parsed; however that could be procrastinated, since today API Extractor performs only minimal TSDoc parsing for dependencies

There might be more, but that's what I remember.

[nicholasrice]

Awesome thanks for the summary @octogonz! I'll give this a whirl and will follow up if I have questions.

[kazupon]

I also hope this feature is supported !

I'm Vue.js core team member and library author. Vue.js has components, directives and etc. If this feature is supported, we can also document them from source code.

[octogonz]

Thanks again @nicholasrice for making a PR. I am on vacation right now but will try to get it reviewed and merged asap. We are very excited about this feature!

[nicholasrice]

No worries @octogonz - enjoy your vacation!

[weareoutman]

Looking forward to this feature too, and I'm wondering does it get stuck or something?