microsoft / microsoft/TypeScript
Inline JSDoc tags don't work in comments that start with plain text
Nobody has claimed this yet.
- Dominant language
- Go
- Stars
- 111k
- Forks
- 14.3k
- Avg merge
- 2d 4h
- Merged PRs (30d)
- 132
Description
TS mostly supports inline tags, even though they're not standard, but the implementation is quirky since it's best-effort, not really a committed feature. Specifically, an inline tag works if the line starts with a non-inline tag, or is a line following such a line:
/** @param foo @see foo.bar */
or
/** @param foo - a long description
* also @see foo.bar */
This is all down to the state machine we use for parsing, so it could be improved to also support
/** for more info @see foo.bar */
Based on discussion in #5802
Contributor guide
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 tracing the JSDoc parsing state machine described in the issue and compare its handling of lines beginning with plain text versus non-inline tags. Done means inline tags such as @see are recognized in the plain-text example while the existing examples continue to work; the payload names no specific files or tests.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- compilers
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Clearly specified
- Newbie friendliness
- 38/100