typescript-and-jsdoc.md

TypeScript + JSDoc

​ With TypeScript, a lot of information can be gleaned from TypeScript itself, either through explicit types or inferred types. So when we use TypeScript along with JSDoc, we could end up duplicating our documentation in some cases. When using JSDoc, we advise you to leave the documentation of types to TypeScript, but still utilize JSDoc to add descriptions. ​

Examples

When using JavaScript, we would use JSDoc to document the type, name (for @param), and description for @param and @returns. ​

/**
 * Divides one number by the other
 *
 * @param {number} a dividend
 * @param {number} b divisor
 * @returns {number} quotient
 */
function divide(a, b) {
  return a / b;
}

​ When using TypeScript, we document our param types explicitly with TypeScript, let our return type be inferred by TypeScript, and add descriptions for @param and @returns with JSDoc. View in TypeScript Playground ​

/**
 * Divides one number by the other
 *
 * @param a dividend
 * @param b divisor
 * @returns quotient
 */
function divide(a: number, b: number) {
  return a / b;
}

​ There are also some constructs that are specific to TypeScript, which we recommend you take advantage of. ​

Resources

• https://dev.to/kamranayub/why-you-don-t-need-types-in-jsdoc-when-documenting-typescript-1pb0
• https://stackoverflow.com/questions/23072286/where-is-the-syntax-for-typescript-comments-documented