Provide API to operate with JSDoc nodes attaches to nodes

[timocov]

🔍 Search Terms

jsdoc api, jsdoc update, jsdoc api

✅ Viability Checklist

• This wouldn't be a breaking change in existing TypeScript/JavaScript code
• This wouldn't change the runtime behavior of existing JavaScript code
• This could be implemented without emitting different JS based on the types of the expressions
• This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, new syntax sugar for JS, etc.)
• This isn't a request to add a new utility type: https://github.com/microsoft/TypeScript/wiki/No-New-Utility-Types
• This feature would agree with the rest of our Design Goals: https://github.com/Microsoft/TypeScript/wiki/TypeScript-Design-Goals

⭐ Suggestion

Initially asked in discord

I'm working on https://github.com/timocov/dts-bundle-generator which is a bundler for type declarations. As part of this tool I've implemented a feature to solve a name collisions issue, i.e. if you have several nodes with the same name but they refer to different symbols then at least one of them should be renamed in order to avoid collisions and/or declaration merging.

The feature is working as expected except one issue that was recently discovered - JSDoc comments stay untouched. E.g. if you have the following code:

// opt.ts
export interface Options {
}

// opt2.ts
/** @see {@link Options.field} */
export interface Options {
    /** @see {@link Options} */
    field: string;
}

// index.ts
export { Options } from './opt';
export { Options as DifferentOptions } from './opt2';

the resulted bundle would be something like this:

export interface Options {
}

/** @see {@link Options.field} */
export interface DifferentOptions {
    /** @see {@link Options} */
    field: string;
}

Now as you can see the issue is that while Options from opt2.ts has been renamed successfully to DifferentOptions (it there are not better candidates it could be something like Options$1 but it doesn't matter here), the JSDoc comment attached to a node left untouched and simply is wrong. The expected output is something like this:

export interface Options {
}

/** @see {@link DifferentOptions.field} */
export interface DifferentOptions {
    /** @see {@link DifferentOptions} */
    field: string;
}

To rename fields I utilize printer's substituteNode feature where I re-create identifiers based on the collision resolver results. The issue is that this function isn't applied to jsdoc comments.

I explored compiler API in order to find anything that can help me to apply the same transformation but to jsdoc comments as I do to the source code, but I couldn't find anything working. It seems there is no even a way to update a jsdoc object attached to a node (e.g. factory.update*-like function but one that you can apply on a node where jsdoc is attached to)? I also checked on https://ts-ast-viewer.com/ and it seems ts.forEachChild doesn't return jsdoc comments at all, only getChildren does.

I tried to utilize printer again by accessing not-exposed node.jsDoc field and applying printer.printNode to a value of that field (yeah its an array so I did in a loop), but it feels like it is not actually applied to all of "children" (e.g. it skips ones that are in a comment field for some reason which causes skipping identifiers in nodes like @see {@link Promise#then}) and it returns a string that I don't know how to assign as a comment to a node back (only "comment-oriented" function I know is ts.setCommentRange).

It is also worth mentioning that I tried to use transformation API and its ts.visitEachChild as well, but it seems that it is even more limited than ts.forEachChild and doesn't go into jsdoc comments at all (I think I found its confirmation in the compiler source code too).

So my question/feature request is - is there an API that I can utilize to traverse jsdoc comments attached to a node, update Identifiers (+ QualifiedNames and JSDocMemberNames)? Ideally I'd like to traverse a node with all jsdoc that it has attached so I don't need to manipulate with nodes and then separately with comments, but either solution is fine if it allows to solve the issue.

I understand that comments might not be a part of idiomatic AST (it can be just a text), but on the other side it contains Identifiers and other pieces of the "language" AST (like identifiers). Also I suppose the language service allows to do a renaming and it renames within jsdoc comments as well which makes me wonder that it might be implemented somehow somewhere (but I'm familiar with this, maybe it is just "replace a text in this range" there).

cc @jakebailey @rbuckton

📃 Motivating Example

The new API that allows to manipulate with JSDoc comments

💻 Use Cases

1. What do you want to use this for? I want to use it to perform JSDoc manipulation to update identifiers mentioned in jsdoc comments
2. What shortcomings exist with current approaches? Nothing that I'm aware of
3. What workarounds are you using in the meantime? None

[RyanCavanaugh]

@sandersn any thoughts?

[timocov]

Any update?

[sandersn]

I don't know the transformer implementation that well, so I don't know how hard this is to add. @rbuckton would know, I think.

As a feature, I think it makes sense. The problem is that traditionally jsdoc was just a blob of text and we've parsed it with more and more detail over time. In particular when I added @link, comment text turned from a string into an array of strings and link parts. That's (semi-)structured data now so it makes sense to be able to transform it.

[timocov]

@rbuckton what do you think? Would it be a feature that I could work on with some guidance from the team?