microsoft / microsoft/tsdoc

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

Open
#335 0 comments 0 reactions 0 assignees View on GitHub

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

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.