Visual Studio: Hyperlink @see to referenced type

[NoelAbrahams]

Hi,

In the following

// file A

module foo {
   export interface Bar {}
}

// file B

module foofoo {

  /** Defines options for creating an instance of @see foo.Bar */ 
  export interface BarOptions {
  }
}

it will be useful if the text referenced by @see (i.e. foo.Bar) is hyperlinked to interface Bar in file A.

[holdfenytolvaj]

+1

[NoelAbrahams]

@sandersn @Kingwl

We've just upgraded to version 4.1 RC and this issue is not fixed for namespaces as outlined above. The issue used the old syntax module for namespace but that shouldn't change anything.

Please can you reopen? Thanks

[Kingwl]

Doube check and It seems work.

[NoelAbrahams]

@Kingwl

The @see only works when it is on a separate line. For example,

this does not work

/** Creates an instance of @see foo.bar */
interface foo {
}

But this works

/** 
 * Creates an instance of 
 * @see foo.bar 
 */
interface foo {
}

I'm not sure whether you see this as a bug, but it's certainly surprising behaviour.

I'm using
Visual Studio Community 2019 Version 16.7.7
Typescript 4.1

Also # 2 you seem to have something that looks like Code Lens (the 0 references | 0 implementations. How do you enable that?

Also # 3 I need to hold down the control key for the hyperlink to appear.

Thanks

[phaux]

@NoelAbrahams I'm pretty sure that JSDoc tags are only allowed at the beginning of the line. There are also inline tags like foo {@link Bar bar} baz but they require braces. A regular tag in the middle of sentence should just be interpreted as regular text.

You probably want to write it like

/** Creates an instance of {@link foo.bar} */
interface foo { }

Typedoc already supports this syntax.

Edit: Even the Github code highlighting recognizes tags only at the beginning of the line or in braces.

[NoelAbrahams]

@phaux thanks for looking that up. I looked up what appears to be the official documentation and there is no clear definition of whether @see should appear on a newline or not — although in the examples they've provided the tag does always appear on a newline.

The fault is in the specification, for lack of clarity, and implementers appear to have decided on not supporting inline @see.

[sandersn]

@NoelAbrahams As you noted, jsdoc.app really only gives examples of one nested tag -- @link. The rest of them are always the first thing on a line.

TS mostly supports inline tags, but the implementation is quirky since it's best-effort, not really a committed feature. Specifically, an inline tag works if the line starts with a non-inline tag, or is a line following such a line:

/** @param foo @see foo.bar */

or

/** @param foo - a long description
 * also @see foo.bar */

This is all down to the state machine we use for parsing, so it could be improved to also support

/** for more info @see foo.bar */

[gdh1995]

@sandersn Thanks for your PR, but it seems that currently the ts-sever in VS Code doesn't support references unless a comment is at the begin of a block / declaration sentence.

I tried such usages:

// this works
if (foo) {
   /** satisfy {@link ConditionsIfFoo} */
   str = getBar()
}

// this doesn't work
if (foo) { /** satisfy {@link ConditionsIfFoo} */
   str = getBar()
}

// this doesn't work
if (foo)
{
}
/** all the below won't satisfy {@link ConditionsIfFoo} */
else if (1) {
} else if (2) {
} else {
}

While highlighting works well for all the 3 cases.

[sandersn]

@gdh1995 can you open a new issue? That's a missing feature that needs a detailed proposal. Currently jsdoc only works when attached to a declaration of some kind. The exceptions are @typedef and @callback, so @link could work like those. However, all 3 tags have complex scope rules, and we'd have to think about how those rules would need to change for @link.

[gdh1995]

Sorry I didn't know a hint would require so many details. I'm unable to give such a proposal, so let me forget it. I'll update my code to try to make tsserver happy.