Preserve JSDocs in *.d.ts files when stripping comments

[dotnetprofessional]

Suggestion/Feature

When using the switch removeComments it will strip out all comments including the ones you may consider useful to the end consumer such as JSDocs. I'd like to strip out any internal comments but preserve any JSDocs comments. It seems that an option to preserve comments in types would be sufficient.

Existing functionality

"removeComments": true,
"declaration": true,

removes all comments including those in *.d.ts files.

Suggested functionality

"removeComments": true,
"declaration": true,

I would think by default you'd want to include the JSDocs in your type defs, so this would remove all comments from the code, but retain any comments associated with the types ie JSDocs.

If however, there is a need to remove all comments then an additional switch may be required to serve that purpose:

"removeCommentsIncludingDeclarations": true,
"declaration": true,

Would produce the same result we have today.

[pocesar]

it makes no sense to remove the comments from declaration files, since they are mainly used during development and won't go into production, I was expecting too that removeComments would only remove them from transpiled .js files.

[DanielRosenwasser]

Legitimate question - why is anyone using removeComments? I would assume that you're using a minifier if you actually care about removing comments, but maybe I'm not aware of other scenarios.

[pocesar]

unminified code not for the browser, mainly. split code base into composable components that will later become part of something bigger (but while in dev, useful being on the consumer part of it). comments in JS = not useful. Comments in .d.ts, uber useful.

Shared code (usually interfaces and mapping objects) that are used in both server and browser, and while it's good to have the comments to be kept in the server side, it's a bad idea to have them shared to the client code (such as comments regarding internal structure, database table names, etc)

[patsissons]

Is this still on the horizon? This is a bit of a pain point with respect to my work-around for #21566 when generating declaration files. Fortunately in my case the declaration file is equivalent to the input source file so i can just replace the generated declaration file with a copied and renamed source file in automation.

[HolgerJeromin]

UglifyJS strips all comments but those with @license or @preserve.

[alexsasharegan]

@DanielRosenwasser, I frequently publish byte-size packages using typescript as my only build step. I usually want my code minified, but my comments available in the declarations since they are doc comments. This is a wonderfully simple way for my to publish packages rather than incorporating a bundler with plugins.

[dotnetprofessional]

HAPPY ONE YEAR ANNIVERSERY!!!!!

Its been exactly 1 YEAR today since this was opened. Are we any closer to having this resolved? This doesn't seem to be a lot of work to fix, but given we've had two duplicates since this was opened, it is something people want. I know I'd like to use it on my OSS projects...

[mindplay-dk]

On a related note: if/when this does get fixed, it would be nice to also adjust the .d.ts output slightly, so that there's a space between doc-blocks and declarations. Currently it's all crammed together.

[dotnetprofessional]

@RyanCavanaugh why mark my reply with a thumbs down? I think its quite valid to ask what's going on with a feature that's been 'In Discussion' for over a year. It would have been more helpful to the community to have spent time replying with an actual update, rather than just being rude!

[championswimmer]

I'd suggest
comments: "never" = no comments
comments: "declaration" = comments are put into the .d.ts files
comments: "emit" = comments are put into emitted js files

[bluelovers]

hope can have this,
i don't think we should use another tool when we wanna remove comment on .js, but keep it on .d.ts

[Ionaru]

@DanielRosenwasser to answer your question:
I think there's a difference between comments used for development and comments used for API consumers.

Comments for development (Starting with // or JSDoc with @internal) live only in the source code and are to help make future development easier. These comments do not need to be in the distribution files as they are of no use for the consumer.

Comments for API consumers (JSDoc) should live either in the declaration d.ts file or in the compiled distribution files. These comments provide explanations of functions, parameters and other things a consumer of the API can use.

My ideal situation:

• Regular comments used for development and JSDocs with @internal are not outputted to the disctribution files.
• The docstring or JSDoc is outputted to the d.ts file.
• The docstring or JSDoc is optionally outputted to the .js file.

Since VSCode looks at the d.ts files for documentation, emitting the JSDoc to d.ts files should have priority over the .js files.

This could use the tsconfig suggestion @championswimmer made.

[bbugh]

I was looking at releasing a typescript library and was really surprised when my comments were either being stripped altogether or completely left in. Having intellisense would be really helpful to end users, but a lot of comments just makes the package size larger.

Though, it did help explain why so many of my third party libraries have nice types but no intellisense documentation.

Is there anything we can do as a community to move this forward? I see official comments, but no confirmation about how to resolve. Given that the proposed solutions are bigger (maybe) not backwards-compatible changes, maybe getting buy-in from one of the core team is important before starting work?

[cinderblock]

Question

Should JSDoc comments be stripped from public APIs of compiled output *.js files?

---

While I'd be happy with @championswimmer's suggestion, I don't see that as compatible with existing options. Based on one discussion that I've had with some on the TS team, one high priority is keep consistent non confusing compiler options. Therefore I'm betting that adding a comments option alongside the existing boolean removeComments option is a non-starter.

Backwards Compatible Solution

What if removeComments was expanded from boolean to boolean | 'none' | 'code' | 'internal' | 'all'?

if (removeComments === false) removeComments = 'none';
if (removeComments === true) removeComments = 'code';

• none - Preserve all comments
• code - Preserve copyright comments
• internal - Preserve JSDoc and copyright comments
• all - Remove all comments

---

Alternative

As the removeComments option does not remove /*! comment blocks, we could add an extra option like preserveJSDocComments that would preserve the appropriate comments when removeComments is set to true.

[loganpowell]

I was going to submit a separate issue, but I believe mine is related. Why can't TypeScript give us docstrings?

[justinasfour04]

Is this going to be fixed

[LSafer]

So this problem became something big? 😪

I thought I could fix it in 5 minutes of googling

If you are here searching for an answer to this issue, DONT typescript does not support it!

[WillsterJohnson]

This suggestion has been in discussion for over half a decade (specifically: 2,041 days at the time of writing).

@RyanCavanaugh do you and your team plan to show an interest in features the community have actively wanted for 2041 days, or will you continue to ignore it for another five years?

This feature is simple, highly requested, and is actually a bug report (@deprecated gets removed from dist code, not good enough). Many people, myself included, are getting increasingly tired of the TS team ignoring their users, we don't want TC39 to make : string a comment, we want this extremely small and simple request to be completed by someone, it will take mere minutes to do yourselves, or even less time to click "merge" on an already submitted PR (this bug was fixed 3 years ago and is still not fixed in production, astounding!)

[webstrand]

@willster277 A workaround using project references: https://github.com/webstrand/typescript-remove-comments-not-from-declarations

Running tsc --build causes the .js files to be generated with "removeComments": true and the generation of .d.ts files is deferred to a sub-project which then generates them without "removeComments": true.

[WillsterJohnson]

@webstrand it's shocking that we have to use 3rd party libraries to fix a Microsoft product.

Actually, it's exactly what I expect from Microsoft, which is arguably even worse.

[webstrand]

@willster277 Actually that's not 3rd-party. The repo's just an example of how to set the project up.

[WillsterJohnson]

@webstrand my bad I'm on mobile, I thought you had sent a fork/project.

I have done this before, but it's not ideal. It would be much better if Typescript didn't destroy information.

[coreyward]

I use TypeScript to generate definitions for my JS source files (for use in libraries), and the lack of carryover from JSDoc comments on functions was disappointing. Since it doesn't seem this will be supported any time soon, I built a post-build script that copies over the JSDoc comments (less redundant type info) for functions declare in the .d.ts type files.

If anybody is interested in trying this approach, I've dropped the script in a gist here: https://gist.github.com/coreyward/e70642a41e2181641a817a632a82cd2d

[zzzgit]

{
"removeComments": true,
"preserveJSDoc": true
}

Hope it can be implemented like this.

[termermc]

One helpful thing would also be to remove type declarations within the preserved JSDoc comments as they're redundant, and may cause issues sometimes.

Additionally, sometimes I use /** @typedef {import('./module.js').Type} Type */ to locally import types, and it's left in verbatim. Pseudo-imports like that should be turned into actual imports ideally.

[michal-kapala]

A sane workaround:

tsc --removeComments && tsc --declaration --emitDeclarationOnly

With tsconfig.json options:

"removeComments": false,
"declaration": false,

Builds stripped JS, then emits declarations with JSDoc preserved.

[alexanderroidl]

This being wanted and not being implemented for about ten years is just sad. Classic Microsoft! 🎉🎉

[unphased]

A sane workaround:

tsc --removeComments && tsc --declaration --emitDeclarationOnly

With tsconfig.json options:

"removeComments": false,
"declaration": false,

Builds stripped JS, then emits declarations with JSDoc preserved.

Could you explain this workaround @michal-kapala ? I have many projects already underway and I really need the d.ts to gain the comments. It seems like this solution requires a deep understanding of how the tsconfig.json options actually interact with command line flags, which I was hoping to avoid as the idea should be that anything you could specify in cli flags should also be configurable via config file...

I have a tsconfig.for_decls.json with

{
  "compilerOptions": {
    "emitDeclarationOnly": true,
    "declaration": true,
    "outDir": "./dist",
    "downlevelIteration": true,
    "removeComments": false
  },
  "files": [ ... ]
}

And it does NOT produce comments in the generated d.ts files.

Edit: I guess I have to specifically use jsdoc style to get it to preserve.

[michal-kapala]

@unphased It is a simple 2-step build:

• the actual build
  • removeComments strips all the comments from the code
  • declarations are not generated just yet (declaration: false in tsconfig)
• declaration emission
  • declaration tells tsc to generate d.ts files
  • emitDeclarationOnly prevents javascript from rebuilding

Options passed via command line override the ones in tsconfig.json, there's not much more to this honestly

[unphased]

Thanks. I figured it out. With my existing setup all I had to do was adjust my comments to Jason/javadoc style with /** and it works well.