microsoft / microsoft/TypeScript

Expose API for getting JSDoc nodes in TypeScript files

Open
#7,393 21 comments 4 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Domain: API In Discussion Suggestion
Dominant language
Go
Stars
111k
Forks
14.3k
Avg merge
2d 4h
Merged PRs (30d)
132

Description

Closure adds various semantic JSDoc annotations that aren't currently modeled by TypeScript, such as @export (unrelated to TS export) and @nosideeffects.
https://developers.google.com/closure/compiler/docs/js-for-compiler#overview

As part of our tool chain to run TypeScript through Closure we'd like to be able to munge these via the TypeScript API. It appears TypeScript gathers JSDoc comments when parsing JavaScript -- is there a good reason to not gather these in TypeScript as well?

Specifically, I believe my suggestion amounts to removing the "if" statement in the below code (though I'm not certain this is the right place) in parser.ts:

        function addJSDocComment<T extends Node>(node: T): T {
            if (contextFlags & NodeFlags.JavaScriptFile) {
                ...all of the code is in here...
            }
        }

Contributor guide

Open the contributing guide

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 in parser.ts at addJSDocComment and inspect how the NodeFlags.JavaScriptFile guard limits JSDoc collection. Compare the existing JavaScript parsing path with TypeScript-file parsing and review the issue discussion for the intended API boundary. Done means JSDoc nodes for TypeScript files can be accessed through the TypeScript API, including Closure annotations such as @export and @nosideeffects.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
compilers
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.