microsoft / microsoft/tsdoc

`eslint-plugin-tsdoc` plugin AST to convert jsdoc to tsdoc on `--fix`

Open
#323 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement
Dominant language
TypeScript
Stars
5k
Forks
162
Avg merge
17h 24m
Merged PRs (30d)
8

Description

I'm tinkering around to see if this is possible but would love to avoid going down a rabbit hole if not likely to work.

https://github.com/wvbe/experimental-jsdoc-to-tsdoc-tool

I've been using a local version of this library to convert any jsdoc blocks autogenerated by a team member's IDE to tsdoc prior to calling @microsoft/api-extractor and before eslint --fix in CI.

It would be awesome if there was an experimental/opt-in way to have eslint-plugin-tsdoc (which already has identified the problem blocks) to auto-convert jsdoc comments to their tsdoc equivalent (and remove non-conforming tags) in real-time via the IDE's eslint integration.

I've been encouraged by the way eslint-plugin-prefer-arrow seems to be able to rewrite function foo() {} to const foo = () => {} reliably, but haven't dug deep enough into eslint to be sure the scenario described above is feasble.

Separate from any sort of official support or implementation - does this sound like something that is actually possible with eslint?

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 reviewing eslint-plugin-tsdoc and the linked experimental-jsdoc-to-tsdoc-tool, then compare their approach with eslint-plugin-prefer-arrow's autofix behavior. Determine whether ESLint can safely rewrite JSDoc comments and remove non-conforming tags through IDE integration; document the feasibility and boundaries of an experimental opt-in implementation.

Written by the indexing model from the issue text.

Assessment

Tech stack
eslint, typescript
Domain
documentation, tooling
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.