Open 0xCLARITY opened 4 years ago
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
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?
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.
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?