Documentation: jsdoc

Content

• Set Up
  • jsdoc-to-markdown
• Cheatsheet
  • Functions
  • Types
  • Variables
  • Typedef
  • Importing types
  • Other keywords
  • React
• References

Set Up

todo: add link to author

To get the the most out of JSDoc with Visual Studio Code, you need to do some setup. In Visual Studio Code, go to Preferences > Settings and add the following line to your user configuration:

"javascript.implicitProjectConfig.checkJs": true

With plain JavaScript this will give you some basic IntelliSense and flag type errors with red squiggles underneath. Hovering over the flagged type error will popup an explanation of the problem.

jsdoc-to-markdown

This is the most lightweight way to add the task - no additional task-running software required. First:

$ npm install jsdoc-to-markdown --save-dev

Then, in the "scripts" section of package.json, add a docs task. For example:

{
  "scripts": {
    "docs": "jsdoc2md lib/*.js > api.md"
  }
}

Now, project documentation is generated like so:

$ npm run docs

Cheatsheet

todo : make own

Vscode generates basic structure: /**

Author: https://devhints.io/jsdoc

Functions

/**
 * This is a function.
 *
 * @param {string} n - A string param
 * @return {string} A good string
 *
 * @example
 *
 *     foo('hello')
 */

function foo(n) { return n }

See: http://usejsdoc.org/index.html

Types

@param {string=} n 	Optional
@param {string} [n] 	Optional
@param {(string\|number)} n 	Multiple types
@param {*} n 	Any type
@param {...string} n 	Repeatable arguments
@param {string} [n="hi"] 	Optional with default
@param {string[]} n 	Array of strings

See: http://usejsdoc.org/tags-type.html

Variables

/**
 * @type {number}
 */
var FOO = 1

/**
 * @const {number}
 */
const FOO = 1

Typedef

/**
 * A song
 * @typedef {Object} Song
 * @property {string} title - The title
 * @property {string} artist - The artist
 * @property {number} year - The year
 */

/**
 * Plays a song
 * @param {Song} song - The {@link Song} to be played
 */

function play (song) {
}

See: http://usejsdoc.org/tags-typedef.html

Importing types

/**
 * @typedef {import('./Foo').default} Bar
 */

/**
 * @param {Bar} x
 */

function test(x) { }

This syntax is TypeScript-specific.

Other keywords

/**
 * @throws {FooException}
 * @private
 * @deprecated
 * @see
 *
 * @function
 * @class
 */

Renaming

/*
 * @alias Foo.bar
 * @name Foo.bar
 */

Prefer alias over name. See: http://usejsdoc.org/tags-alias.html

React

https://react-styleguidist.js.org/docs/documenting.html

References

https://devhints.io/jsdoc