Typescript: 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 future development easier. These commends 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?

[nealeu]

HAPPY TWO YEAR ANNIVERSARY.

@RyanCavanaugh (or anyone else at Microsoft): are you going to respond or just :-1: this too?

Looking at recent releases I'm getting tempted to look at Kotlin for JS now. Building and using libraries in with Typescript is still way off from the simplicity and consistency of Java/Maven ecosystem.
Now that MS has control of NPM too, then isn't this an opportunity to bring the JS ecosystem up.

But until then... can we please have this simple feature to retain JSDoc... PLEASE!

[bluelovers]

hope one day something like this can be merge
https://github.com/microsoft/TypeScript/pull/31813

[rbonestell]

Official TypeScript documentation describes the implementation of JSDoc without mentioning this behavior. I think the implicit behavior should be something such as the solutions described above, but the documentation should _explicitly_ describe the behavior.

[mindplay-dk]

I'm sure a pull request (with test-coverage and documentation) wouldn't be rejected by the team - this is one of those "duh, obvious" features no one can really object to.

But to those of you who think this is a slam dunk and why doesn't it "just" get done: I gave it a shot, and about an hour later, all I've managed to do is run the test-suite, ha ha.

The feature itself is probably something like changing the type of removeComments to something like true | false | "preserve-doc-blocks", then testing for that in the condition here - but there are many types of JSDoc nodes, it's not obvious what to do with all of them (esp. the ones on interfaces and other declarations that don't get emitted) and the test-suite needs to be updated, and doesn't seem to have test-coverage for removal of comments in the first place, so that probably needs to be added first, the feature needs documentation, and so on.

Iterating on a codebase of this size and complexity is never quick or easy - there are only so many developers working on this, and I'm sure they have priorities, and yeah, sometimes apparently simple things take more than two years. If you think it's so easy, why don't you do it and submit a PR 😀

[Zzzen]

Currently, all comments are removed from d.ts when removeComments is false. Am I missing anything?

playground

[thealjey]

@Zzzen yes, you are
this is about JSDoc comments specifically

[Zzzen]

😕 Do you mean normal comments are never preserved by design?

[thealjey]

in a declaration file?
of course they are not

[Zzzen]

So do you have any idea why // interface Foo is removed in .D.TS section? @thealjey