5

Following the official instructions in Creating .d.ts Files from .js files, I am trying to generate definitions for a JSDoc @enum.

/**
 * The direction enum.
 * 
 * @enum {number}
 */
const Direction = {
  /**
   * Up direction.
   * 
   * @type {number}
   * @constant
   */
  Up: 1,
  /**
   * Down direction.
   * 
   * @type {number}
   * @constant
   */
  Down: 2,
  /**
   * Left direction.
   * 
   * @type {number}
   * @constant
   */
  Left: 3,
  /**
   * Right direction.
   * 
   * @type {number}
   * @constant
   */
  Right: 4,
};
export default Direction;

For my tsconfig.json, I made sure that removeComments is set to false. I expect to see all the documentation for all the properties of the Direction object to carry over to the .d.ts file, however, I see the following output:

export default Direction;
/**
 * The direction enum.
 */
type Direction = number;
declare namespace Direction {
    const Up: number;
    const Down: number;
    const Left: number;
    const Right: number;
}

You can try it for yourself on the TS Playground. How can I ensure that all the documentation properly carries over?

Sam Fischer
  • 1,442
  • 19
  • 35
  • Not that this fixes anything, but that playground link has `removeComments` as `true`, not `false`. – jcalz Sep 07 '22 at 18:37
  • Thanks for pointing that out @jcalz. Link has been updated. – Sam Fischer Sep 07 '22 at 20:35
  • [Here](https://stackoverflow.com/q/36488644/1048572) an alternative method of documenting enums with jsdoc is suggested – Bergi Sep 10 '22 at 22:27
  • I would suggest you just file a bug report for the missing doc comments. However, notice that [*`@enum` is quite different from, and much simpler than, TypeScript’s `enum`*](https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html#enum) (also [here](https://github.com/microsoft/TypeScript/issues/30624)), and you can see that it's generating a `namespace` declaration not an enum. – Bergi Sep 10 '22 at 22:30
  • Is there any reason why you want to use javascript with type annotations in comments instead of just writing typescript? – Bergi Sep 10 '22 at 22:31
  • @Bergi In cases of existing libraries, generating TypeScript definitions to support TypeScript users is easier than porting everything to TypeScript. – Sam Fischer Sep 11 '22 at 00:29

1 Answers1

1

As a workaround, you could use both @typedef and @property tags.

I can't see why we'd add @readonly, though, since TypeScript constants already represent variables whose values cannot be modified and the Direction object literal, as it is currently defined, it's not truly readonly.

Take the definition below as an example:

/**
* @typedef Direction
* @property {number} Up "Up direction"  
* @property {number} Down "Down direction" 
* @property {number} Left "Left direction" 
* @property {number} Right "Right direction"
*/
const Direction = {
  Up: 1,
  Down: 2,
  Left: 3,
  Right: 4,
};
export default Direction;

Would generate the following .d.ts file:

export default Direction;
export type Direction = {
    /**
     * "Up direction"
     */
    Up: number;
    /**
     * "Down direction"
     */
    Down: number;
    /**
     * "Left direction"
     */
    Left: number;
    /**
     * "Right direction"
     */
    Right: number;
};
declare namespace Direction {
    const Up: number;
    const Down: number;
    const Left: number;
    const Right: number;
}

Would that work for your use case?

Cheers

Moa
  • 1,456
  • 4
  • 20
  • Thanks @Moa. This comes close, but it seems like this is just a missing feature of `tsc` at the moment. But I think anyone else running into this issue would probably find this a satisfactory workaround. – Sam Fischer Sep 13 '22 at 18:06
  • Yep, that's definitely a missing feature of `tsc`. Glad to help. – Moa Sep 13 '22 at 22:35