Repository: TypeScript
Issue: New "persistentDocumentation" and removeComments
Labels: Suggestion,Awaiting More Feedback

<!-- 🚨 STOP 🚨 𝗦𝗧𝗢𝗣 🚨 𝑺𝑻𝑶𝑷 🚨

Half of all issues filed here are duplicates, answered in the FAQ, or not appropriate for the bug tracker.

Please help us by doing the following steps before logging an issue:
  * Search: https://github.com/Microsoft/TypeScript/search?type=Issues
  * Read the FAQ, especially the "Common Feature Requests" section: https://github.com/Microsoft/TypeScript/wiki/FAQ

-->

## Search Terms

<!-- List of keywords you searched for before creating this issue. Write them down here so that others can find this suggestion more easily -->
removeComments documentation comments removed persistentDocumentation
## Suggestion

<!-- A summary of what you'd like to see added or changed -->
In the current version of TypeScript, when `removeComments` is set to `true`, it removes all comments except copy-right header comments beginning with `/*!`. This is very useful, but I think it can be refined.

### My actual suggestion
In my JavaScript editors, comments beginning with `/**` are treated as a kind of JSDoc comment, which describes the function directly below it. If `removeComments` is set to `true`, then it also removes these documentation comments which can be VERY useful. So, I want to propose a change to this setting. Everything says the same, but when `"removeComments": true` is combined with something like `"persistentDocumentation": true`, the compiler removes all comments except for comments beginning with either `/*!` OR `/**`.

## Use Cases

<!--
What do you want to use this for?
What shortcomings exist with current approaches?
-->
My current approach includes just leaving `removeComments` off. This is not ideal, as there are many comments that are for devs and devs only, but there are also many JS documentation comments that are meant for the person using the library.

With this suggestion, no changes would be made to any current compiler settings. The user must know of this feature and change their compiler settings. This feature would only benefit the TS community.

## Examples (using ES6 export)

<!-- Show how this would be used and what the behavior would be -->
```typescript
/*!
 Super-awesome legal statement
*/

// The adding function
/**
 * Returns the sum of two addends
 * @param number1 The first addend
 * @param number2 The second addend
 */
export function add(number1: number, number2: number): number {
    return number1 + number2; // Return the number
}

/*
Continue to build out this library.
Future additions:
Subtraction
Multiplication
Exponents
Factorials
*/
```

We all know what just `removeComments` would do, so the same but with `persistentDocumentation`:

### The main file, compiled

```javascript
/*!
 Super-awesome legal statement
*/
export function add(number1, number2) {
    return number1 + number2;
}
```

### The .d.ts file

```typescript
/*!
 Super-awesome legal statement
*/
/**
 * Returns the sum of two addends
 * @param number1 The first addend
 * @param number2 The second addend
 */
export function add(number1: number, number2: number): number;
```

Very handy indeed!

## An alternative
Instead of this, which would be ideal, something could be set up with the ts-to-js map file that can be generated, which maps the documentation comments to the compiled js file, but as mentioned, this is... less than ideal. Also, I can imagine it would be harder to code.

I just wanted to throw this out there just in case.

## Checklist

My suggestion meets these guidelines:

* [x] This wouldn't be a breaking change in existing TypeScript/JavaScript code
* [x] This wouldn't change the runtime behavior of existing JavaScript code
* [x] This could be implemented without emitting different JS based on the types of the expressions
* [x] This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, etc.)
* [x] This feature would agree with the rest of [TypeScript's Design Goals](https://github.com/Microsoft/TypeScript/wiki/TypeScript-Design-Goals).