[Question] How is JSDoc handled ?

[tommywalkie]

First of all, this is very nice work ! 👍

A bit of context, I used to transpile some TypeScript files (with tons of JSDoc comments) with tsc and then generate developer documentation with some tool named Docma.

Now I'm trying esbuild (JavaScript API) and I noticed it keeps classes related JSDoc comments in the output but ignores the ones related to constructors or methods or enums, here is an example where we have a Movie class with some string property actually related to an enum ISO_639_1.

Input

/**
 * Enum for ISO_639-1 language codes.
 * @readonly
 * @enum {string}
 */
export enum ISO_639_1 {
	/** French */
	FR = 'fr',
	/** English */
	EN = 'en',
	/** German */
	DE = 'de',
	/** Italian */
	IT = 'it'
}

/**
 * Some basic TypeScript class
 * @public
 * @constant
 * @class Movie
 * @property {ISO_639_1}  language
 * @copyright Tom Bazarnik and the contributors
 * @license GNU General Public License v3.0
 */
export class Movie {
    language: ISO_639_1
	/**
         * Creates an instance of Movie.
         * @param {ISO_639_1} [language='en'] - Primary language
         * @constructor
         */
	constructor(language: ISO_639_1 = ISO_639_1.EN) {
		/**
                 * Some name string
                 * @type {ISO_639_1}
                 * @public
                 */
		this.language = language
	}

	/**
         * Set language
         * @method
         * @param {ISO_639_1} language - Primary language
         */
	setLanguage(language: ISO_639_1) {
		this.language = language
	}
}

Output

This is the output (tested with minify parameter with both false and true values) :

export var ISO_639_1;
(function(ISO_639_12) {
  ISO_639_12["FR"] = "fr";
  ISO_639_12["EN"] = "en";
  ISO_639_12["DE"] = "de";
  ISO_639_12["IT"] = "it";
})(ISO_639_1 || (ISO_639_1 = {}));
/**
 * Some basic TypeScript class
 * @public
 * @constant
 * @class Movie
 * @property {ISO_639_1}  language
 * @copyright Tom Bazarnik and the contributors
 * @license GNU General Public License v3.0
 */
export class Movie {
  constructor(language = ISO_639_1.EN) {
    this.language = language;
  }
  setLanguage(language) {
    this.language = language;
  }
}
//# sourceMappingURL=Movie.js.map

Right now, I'm not sure if this is because I'm missing some settings, or if the issue is somewhere else.

[evanw]

The comment is only being preserved because it contains the text @license. This behavior is not general-purpose and esbuild is not intended to do general comment preservation. For example, the comment may be kept while the class after it is removed due to dead code elimination. You're probably better off using a different tool if you need to preserve comments generally like this.

[tommywalkie]

@evanw Thanks for the explanation. Again, I want to say, esbuild is really great, I was just curious about this very specific use case. We can close the issue.

[mesqueeb]

@evanw is it possible to keep all JSDoc comments?

My use case is JS utils and small libraries I write and host on NPM. No minifying/sourcemaps, only bundling to esm format.

The beauty about JSDoc comments is that a lot of editors (like VSCode) show popup information when a function is imported that has JSDoc comments.

The information can vary from just developer notes to the type of arguments and return types.

I'm evaluating replacing rollup from esbuild.

If esbuild can only strip JSDoc comments, is there some way I can retain the popup information that editors support?

[evanw]

No, there is no way to do this with esbuild. You're better off using Rollup in this case.