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

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.

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:

What happens if you have multiple @see tags?

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.

What happens if you have multiple @see tags?

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 ....

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.

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?

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.

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:

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?

I'm not sure we can issue a warning, because @see Elements is exactly what you would write if you intended to put plain text in your bullet. (How to disable an unintended link? @see \Elements?)

Thinking about this, if someone is using TSDoc to parse legacy JSDoc comments, they probably do not care a whole lot about some missing hyperlinks. The people requesting "lax" rules seem mainly concerned with suppressing TSDoc errors, because errors require work to fix. If a legacy notation can be reliably detected (e.g. @param x {string}) then sure, TSDoc can parse it. But it shouldn't impact parsing of inputs that follow the strict rules.

Does that make sense?

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

This is exactly the behavior I would expect from TSDoc for precisely the reason you describe. TSDoc makes it possible to look at a comment and know exactly what will be rendered. This is a huge benefit to using it.

@octogonz, should we close this since #236 got merged?

Good point. I really want to go implement this for API Extractor. It's so little work. :-)

Since this is an RFC, let's keep this issue open. All the RFC issues will get closed when the formal spec is completed.