Here are the key best practices for using JSDoc with TypeScript:
Avoid redundant type annotations since TypeScript already provides comprehensive type information[1][2]. Instead, use JSDoc to document the purpose, behavior, and usage of your functions and classes[2].
/**
* Calculates the compound interest for an investment
* @param principal - The initial investment amount
* @param rate - Annual interest rate (as decimal, e.g., 0.05 for 5%)
* @param time - Investment period in years
* @returns The final amount after compound interest
*/
function calculateCompoundInterest(principal: number, rate: number, time: number): number {
return principal * Math.pow(1 + rate, time);
}TypeScript officially supports most JSDoc tags[3]. The most commonly used tags include:
@param- Describe parameter purpose and constraints (not types)@returns- Explain what the function returns and when@example- Provide usage examples@deprecated- Mark outdated functionality@remarks- Add additional context or warnings
TSDoc is Microsoft's proposed standard for TypeScript documentation comments[4]. It provides a more structured approach and better tooling support:
/**
* Returns the average of two numbers.
* @remarks
* This method is part of the {@link core-library#Statistics | Statistics subsystem}.
* @param x - The first input number
* @param y - The second input number
* @returns The arithmetic mean of `x` and `y`
* @beta
*/JSDoc comments appear in IntelliSense tooltips, making them valuable for shared utilities and public APIs[2]. This improves the developer experience by providing context without requiring developers to navigate to source code.
Don't document everything[2]. Focus on:
- Complex or non-obvious functionality
- Public APIs and shared utilities
- Functions with specific usage constraints
- Methods that might have side effects
TypeScript supports these JSDoc constructs for documentation[3]:
@param,@returns,@example@deprecated,@since,@see@throws,@remarks- Property modifiers:
@public,@private,@protected,@readonly
The key is to complement TypeScript's type system with meaningful descriptions that help other developers understand the intent and proper usage of your code.
[1] https://www.reddit.com/r/typescript/comments/1519zn4/param_or_is_there_official_documentation_on_how/ [2] https://www.reddit.com/r/typescript/comments/r3srin/do_you_use_jsdocs_with_typescript/ [3] https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html [4] https://tsdoc.org [5] https://blog.bitsrc.io/documenting-your-typescript-projects-there-are-options-da7c8c4ec554 [6] https://stackoverflow.com/questions/42948252/typescript-are-there-any-conventions-to-document-code-with-comments [7] https://www.oracle.com/technical-resources/articles/java/javadoc-tool.html [8] https://www.pullrequest.com/blog/leveraging-jsdoc-for-better-code-documentation-in-javascript/ [9] https://dev.to/cherryramatis/what-is-jsdoc-and-why-you-may-not-need-typescript-for-your-next-project-54n1 [10] https://github.com/vojtechhabarta/typescript-generator/wiki/Javadoc