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

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?

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:

Good point. I really want to go implement this for API Extractor. It’s so little work. 😃

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.

What happens if you have multiple @see tags?