[api-extractor] Add support for @example in AEDoc

[hansl]

Used for showing example of usage of a class/method. Can have more than
one example per item.

[octogonz]

Thanks for creating this PR! It seems like a pretty useful feature.

In your PR could you give a URL for an example web site somewhere that models how you expect the multiple examples would get rendered? (Can any text come after the examples? Do the examples have any headers/titles to distinguish them? Is it rendered differently when there is only one example? etc.) If you encounter any interesting design considerations, you could mention them in microsoft/tsdoc#20 were we recently discussed @example for the upcoming TSDoc standard.

If you feel like doing more work ( :-P ), you could also add a basic reference implementation in the markdown target for api-documenter. This simplistic implementation is used for the web-build-tools API reference and would allow us to demo the feature.

Thanks again @hansl!

[hansl]

Hi @pgonzal ,

Seems like your description in the tsdoc discussion is exactly what we use it for. It can contain any text, but normally for us it's just code.

[hansl]

I don't have time to work on this anymore. There doesn't seem to be any process described in your CONTRIBUTING document.

I'll close this and come back when I have time. We can use jsdoc with special support for typescript in the meantime.

Thanks!

[HarryGifford]

Hey @hansl What work still needs to be done? This would be a really helpful addition. The lack of @example support is a real kicker.

[hansl]

Hi @HarryGifford,

I agree, but I cannot fix the problems and examples with this PR, and the submission workflow in this repository is not well described (and not intuitive in comparison to other OSS projects). Unless I didn't look at the right places, I have no idea what to do to support all tests and the build system (and changelog, etc). The CONTRIBUTING file doesn't have that information, and there's no information anywhere on how to make a proper contribution.

This PR can be used as a base for it. The crux of the work is done, it works when tested locally. I'm unfortunately busy with other work right now.

[octogonz]

Sorry about that! I've been on vacation all month and just got back. I'll see if we can improve the CONTRIBUTING guidelines for this repo.

This PR can be used as a base for it. The crux of the work is done, it works when tested locally. I'm unfortunately busy with other work right now.

The @example feature seems pretty useful and important. Thanks for your work on this PR. If you don't mind, I'm going to reopen your PR to make sure this issue gets solved.

However, in order to write the examples, don't you also need to code syntax highlighting (i.e. markdown backticks)? That feature is missing from the current API Extractor, but is now implemented in the TSDoc parser. In the next few weeks I'm going to be working to integrate TSDoc into API Extractor, which should address that.

[hansl]

However, in order to write the examples, don't you also need to code syntax highlighting (i.e. markdown backticks)? That feature is missing from the current API Extractor, but is now implemented in the TSDoc parser. In the next few weeks I'm going to be working to integrate TSDoc into API Extractor, which should address that.

If you do (and move API Extractor to using TS 2.9 or even 3.0), I'd love the Angular CLI to be used as guinea pig for those features. I have a branch that uses AE and JSDoc currently, albeit with local patches, and I don't have time to pursue those patches upstream.

[hansl]

I'm on gitter relatively often, or we can start a discussion by email at hansl@google.com.

[HarryGifford]

Thank you for your work on this @hansl

[octogonz]

@hansl It turns out that this PR will be superseded by API Extractor 7 (PR #951), which replaces the MarkupElement structures with TSDoc's DocNode trees (which are a more standardized and better supported representation). Also, they can be embedded in the .api.json files as doc comment strings, which gives us a robust serializer/deserializer for free.

You can see an example of how @example gets rendered in this test case. If you think the rendering or behavior of the @example tag could be improved, please let us know. Thanks for driving this effort. It's a useful feature!