[Member] links don't render

[joeduffy]

We seem to use [Type] and [Method(func)] annotations in some of our API documentation, presumably hoping that these will get rendered as hyperlinks. For example, see Output:

At ‘deployment time’, the correct way to work with the underlying value is to call [Output.apply(func)]. This allows the value to be accessed and manipulated, while still resulting in an [Output] that is keeping track of [Resource]s appropriately. At deployment time the underlying value may or may not exist (for example, if a preview is being performed). In this case, the ‘func’ callback will not be executed, and calling [.apply] will immediately return an [Output] that points to the [undefined] value. During a normal [update] though, the ‘func’ callbacks should always be executed.

I assume the [Output.apply(func)], [Resource], [.apply], and various [Output]s, are intended to be hyperlinked to the relevant members?

This pattern is prevalent in the Pulumi SDK itself in addition to addition to packages like AWSX (Crosswalk). I believe @CyrusNajmabadi has written most of them, so we should ask whether this is a convention that should be being respected, or maybe the API docs themselves are simply wrong and should use a different syntax.

[CyrusNajmabadi]

Yeah, basically this was a way to just call things out as being 'code related'. Happy to actually switch everything to an appropriate hyperlinking form once someone can tell me what that form should be that is reasonable stable :)

[justinvp]

We should investigate whether using JSDoc {@link} would do what we want. (Need to see how this comes back from TypeDoc).

https://jsdoc.app/tags-inline-link.html

[CyrusNajmabadi]

There's no rhyme or reason on [] usage. It's just a way to callout that something is code versus non-code. I'm happy to go and adopt any sort of pattern that actually works. If we can make some sort of hyperlinkable tag, that would be excellent. @justinvp can you check and see what works and report back? i can then update our libs accordingly. Thanks!

[justinvp]

Yep, I'll take a look and report back.

[justinvp]

Editor support for @see and {@link} in JSDoc comment tags is on the roadmap for TypeScript 4.1. https://github.com/microsoft/TypeScript/issues/35524