RFC: `@see` block tag specifies an item for a "See Also" section

[0xCLARITY]

I use the eslint-plugin-tsdoc for linting, and noticed that the JSDoc @see tag is not supported in the list of TSDoc tags.

We use @see tags extensively in one of our projects, so it would be great to add support for it so the TSDoc ESLint plugin doesn't warn for using that tag.

I'm happy to write a PR. Is all it takes adding this to the list of TSDoc tags?

[octogonz]

We discussed the @see and @seealso tags a few times before. I had trouble finding a spec for how they are supposed to be rendered by a documentation system.

You can already write this:

/**
 * Adds numbers using arithmetic.  
 * @remarks
 * For more information, see {@link https://en.wikipedia.org/wiki/Arithmetic|Arithmetic}.
 * @param x - the first number
 * @param y - the second number
 * @returns the sum.  For more information, see also {@link subtractNumbers}.
 */
function addNumbers(x: number, y: number): number;

I know that DocFX can render a "See Also" section. But it is a bulleted list of references.

You could simulate it with a heading and markdown bullets (not yet parsed by TSDoc but coming soon):

/**
 * Adds numbers using arithmetic.  
 * @remarks
 * Some more information here.
 *
 * # See Also
 * - {@link https://en.wikipedia.org/wiki/Arithmetic|Arithmetic}.
 * - {@link subtractNumbers}
 *
 * @param x - the first number
 * @param y - the second number
 * @returns the sum
 */
function addNumbers(x: number, y: number): number;

...which might get rendered like this:

---

addNumbers() function

function addNumbers(x: number, y: number): number;

Adds numbers using arithmetic.

Remarks

Some more information here.

See Also

• Arithmetic
• subtractNumbers

---

Based on this, I could imagine some value in standardizing a @seealso tag, if this is a very common pattern that API docs typically do (although this is debatable):

/**
 * Adds numbers using arithmetic.  
 * @remarks
 * Some more information here.
 *
 * @seealso
 * - {@link https://en.wikipedia.org/wiki/Arithmetic|Arithmetic}.
 * - {@link subtractNumbers}
 *
 * @param x - the first number
 * @param y - the second number
 * @returns the sum
 */
function addNumbers(x: number, y: number): number;

But JSDoc's @see tag doesn't seem to intended for either of these scenarios.

@hbergren how are you using @see in your documentation?

CC @rbuckton

[octogonz]

I'm also interested to know more about JSDoc's semantics. Their docs give this example:

/**
 * @see {@link foo} for further information.
 * @see {@link http://github.com|GitHub}
 */
function bar() {}

But it doesn't explain how it would get rendered by the documentation system.

[rbuckton]

You cannot emulate @seealso properly with DocFX, as how seealso entries are rendered depends on the DocFX template in place since they are unique items in the schema.

Also, @see is supported by the jsdoc package:

[octogonz]

What happens if you have multiple @see tags?

[rbuckton]

Essentially, @see items are rendered in a list. @see foo interprets foo as a namepath, while @see {@link foo} bar allows you to add freeform text.

The reason I based #205 on synonyms is that DocFX calls this a seealso.

[rbuckton]

What happens if you have multiple @see tags?

[rbuckton]

The XML doc comment <see cref="..." /> ¹ is synonymous with JSDoc's {@link ...}, while the XML doc comment <seealso cref="..." /> ² is synonymous with JSDoc's @see ....

[octogonz]

Ahh ok. So @see is a block tag where each block becomes one item in a list of references.

If our documentation template uses bullets, then our spec is that this input (with intentionally scrambled ordering)...

/**
 * Adds numbers using arithmetic.  
 * @see {@link https://en.wikipedia.org/wiki/Arithmetic|Arithmetic}.
 * @remarks
 * Some more 
 * information here.
 * @see 
 * {@link subtractNumbers}
 * @see *Elements* 
 * by Euclid
 * @param x - the first number
 * @param y - the second number
 * @returns the sum
 */
function addNumbers(x: number, y: number): number;

...might get rendered like this:

---

addNumbers() function

function addNumbers(x: number, y: number): number;

Adds numbers using arithmetic.

Remarks

Some more information here.

See Also

• Arithmetic
• subtractNumbers
• Elements by Euclid

---

That seems like a pretty useful and reasonable design.

[octogonz]

JSDoc also specifies:

You can provide either a symbol's namepath or free-form text.

This aspect seems problematic. Namepaths are ambiguous with free-form text.

For example, if instead of this:

 * @see *Elements* 
 * by Euclid

...I wrote it as:

 * @see Elements

...then how is the parser supposed to know whether Elements was meant to be an API item reference or a free-form title?

Thus I'd propose that TSDoc omit this aspect and instead require an explicit {@link} for any hyperlinks with @see.

Are you guys okay with that?

[rbuckton]

I would say its something like a block tag, yes. And you are correct they would all be grouped together. I imagine it should behave similar to something like this:

/**
  * @param foo
  * @remarks some remarks...
  * @param bar
  */
function f(foo, bar) { ... }

I would expect the @param tags to be grouped.

[rbuckton]

In @hbergren's version of my @see PR I commented that it would be useful to support both with a warning on the @see Elements case to better support anyone who might be converting from jsdoc to tsdoc?

For context, jsdoc parses @see hello world first as if it were @see {@link hello} world, but if it can't resolve hello it leaves it as normal text. Also, VSCode highlights the first word after @see as if it were a namepath: