[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. microsoft/TypeScript#35524

[thoward]

So, looking into this a bit... it seems that we've update the notation from when this was filed. However, this issue still persists somewhat. For example here: https://github.com/pulumi/pulumi/blob/24e72c9b515639d4ad9bd596164f376553085555/sdk/nodejs/output.ts#L1003

 * At "deployment time", the correct way to work with the underlying value is to
 * call {@link Output.apply}. This allows the value to be accessed and

renders as "call Output.apply" in plaintext, w/ no link to the apply function (see currently published docs).

That's because TypeDoc doesn't generate docs for methods on type aliases like Output.apply, however it does generate docs for OutputInstance.apply. It seems like the intention would be for the link to resolve to: the apply function on the OutputInstance doc page, or for the Output type alias docs to also have the methods from the types it was composed from.

However, this kind of issue seems unresolvable with the way that we've structured the classes and the way that types are resolved in TypeDoc. I've dug around in their issues and a number of people have similar problems and they basically closed them all as wont-fix with complex explanations about how TypeScript works. So, I'm guess we aren't ever going to get a fix for this.

That said, we have a little control here in a hacky way. We could write these links like this: {@link OutputInstance.apply | Output.apply}, which will cause it to use link text "Output.apply" but link to the docs for "OutputInstance.apply".

Regardless, it's been 5.25 years since this issue was filed, and there's no obvious/easy way to resolve it any time soon, so I'm going to close it as wont-fix here. We can reopen if/when such support is implemented in TypeDoc.