Website: https://jsdoc.app/
Getting Started: https://jsdoc.app/about-getting-started.html
Tips and tricks
enums
https://jsdoc.app/tags-enum.html
Unless I've missed some clever trick somewhere, the enum type safety in JSDoc is weaker than with TypeScript. You cannot get exhaustivity checks. Still, there is some safety in their declaration.
const ProviderNoEnum = {
GOOGLE: "google",
TWITCH: "twitch",
FACEBOOK: "facebook",
}
ProviderNoEnum.OTHER // no error
/**
- Enum of providers.
*
- @enum {string}
*/
const Provider = {
GOOGLE: "google",
TWITCH: "twitch",
FACEBOOK: "facebook",
};
Provider.OTHER // error
There were some Stack Overflow posts related to using the @property tag but I didn't see the benefit it conferred to type strength when testing with it.
parameter types
https://jsdoc.app/tags-param.html https://jsdoc.app/tags-param.html#parameters-with-properties
Use @param
/**
- @param {Object} input description text
- @param {string} input.a description text
- @param {number} input.b description text
- @param {Object} input.c description text
*
- ## Multiline description text
*
- With markdown support. Describes `input.c`, * and does not affect the
- `@param` declarations around it
*
- @param {string} input.c.d description text
- @returns {string}
*/
function abc({ a, b, c }) {
}
Optional parameters
/**
- @param {Object} input
- @param {string} input.a required
- @param {number} [input.b] optional
*/
types
https://jsdoc.app/tags-type.html
typedef
https://jsdoc.app/tags-typedef.html
In one js project I am using a paradigm of creating typedefs from return types of functions. For example, if getDb was a function that returned a db object.
/**
- @typedef {ReturnType<typeof getDb>} Db
*/
function getDb() {}
enable JSDoc errors and warnings in VSCode
VSCode is using TypeScript to enable this functionality, so it is a TypeScript setting. Search for "check js". As of this writing it is in Extensions >TypeScript > JS/TS > Implicit Project Config: Check JS.