microsoft / tsdoc

A doc comment standard for TypeScript
https://tsdoc.org/
MIT License
4.7k stars 130 forks source link

tsdoc-html-tag-missing-greater-than False Positive? #335

Open WesleyMConner opened 1 year ago

WesleyMConner commented 1 year ago

The eslint-plugin-tsdoc appears to be issuing a false-positive "tsdoc/syntax" linter error when Generator or AsyncGenerator types appear in a tuple. ["eslint-plugin-tsdoc": "0.2.16"]

The linter DOES NOT complain for a simple case like the following:

/**
  *  :
  * @returns AsyncGenerator<Buffer, string, undefined>
  */

The linter DOES complain if the generator type appears in a named tuple.

/**
  *  :
  * @returns [stdoutGen: AsyncGenerator<Buffer, string, undefined>, stderrGen: AsyncGenerator<Buffer, string, undefined>]
                                       ^The HTML tag has invalid syntax: Expecting an attribute or ">" or "/>"
  */

EDIT: I see that escaping < with \< satisfies the linter. Is this expected?

The linter DOES complain if the generator type appears in a (not named) tuple.

/**
  *  :
  * @returns [AsyncGenerator<Buffer, string, undefined>, AsyncGenerator<Buffer, string, undefined>]
                            ^The HTML tag has invalid syntax: Expecting an attribute or ">" or "/>"
  */

The linter DOES NOT complain if a type alias is introduced for AsyncGenerator<Buffer, string, undefined>.

/**
  *  :
  * @returns the tuple [stdoutGen: AsyncBufferGenerator, stderrGen: AsyncBufferGenerator]
  */

BUT, ... adding types to avoid a linter complaint feels like a step toward "type hell" (in the spirit of "callback hell", "promise hell" ...).

What is the best approach in this situation? (a) escape the < with \< (b) enhance the linter to accept the construct (c) enhance the linter to improve the error message (d) mute the linter rule (e) add the intermediate type (side-step the error) (f) other

I suspect the answer may relate to any constraints imposed by best-practices or downstream "compatible documentation tools".

Thanks in Advance!