Inline JSDoc tags don't work in comments that start with plain text

[sandersn]

TS mostly supports inline tags, even though they're not standard, 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 */

Based on discussion in #5802

[sandersn]

@NoelAbrahams you were interested in seeing this work, I believe. I marked it Awaiting More Feedback because I don't remember this usage being widespread in the earlier survey I did. However, the fix is likely quite contained to the central JSDoc parsing state machine, so it might be easy to fix even if it's not widely used.

[NoelAbrahams]

@sandersn

Thanks for following up on this.

I certainly see the fact of @see not working inline as an unnecessary restriction that can surprise the user.

The C# see comment allows specifying the tag inline. And my instinct was to write it like that.

We have a common use case for this where there are constructor option objects that create a certain type, eg

interface Foo {
}

/** Creates an instance of @see Foo */
type FooOptions = { bar: string; };

There is no easy way to break up the comment into a newline in a meaningful way.

[sandersn]

Yep, JSDoc is subtly different from C#, and the spec tag for that is @link. But TS doesn't support @link at all right now and besides, a language service should be flexible and match expectations of multiple groups of users.