tsdoc-html-tag-missing-greater-than False Positive?
Nobody has claimed this yet.
- Dominant language
- TypeScript
- Stars
- 5k
- Forks
- 162
- Avg merge
- 17h 24m
- Merged PRs (30d)
- 8
Description
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!
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reproducing the simple, named-tuple, unnamed-tuple, escaped, and type-alias examples with eslint-plugin-tsdoc 0.2.16. Compare the reported diagnostics and determine whether the tuple syntax should be accepted, whether the message should improve, or whether documentation should recommend an escape; done means reaching and documenting a clear expected behavior.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- documentation
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 28/100