New "persistentDocumentation" and removeComments

Search Terms

removeComments documentation comments removed persistentDocumentation

Suggestion

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

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)

/*!
 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

/*!
 Super-awesome legal statement
*/
export function add(number1, number2) {
    return number1 + number2;
}

The .d.ts file

/*!
 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:

• 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, etc.)
• This feature would agree with the rest of TypeScript’s Design Goals.

[AviVahl]

To add to the suggestion above, I also think there should be a distinction between regular comments and jsdocs, but another useful distinction would be *.js vs. *.d.ts files.

Or to be clearer, my suggestion is to have a mode that:

• For *.d.ts - keeps jsdocs/license comments. Removes all other comments.
• For *.js - keeps just the license comment.

[keithlayne]

Unless there’s an alternate spelling that I couldn’t find, “persistent” is the correct spelling.