jsdoc.md

   1 ---
   2 title: Jsdoc
   3 category: JavaScript
   4 layout: 2017/sheet
   5 updated: 2020-06-23
   6 weight: -1
   7 ---
   8
   9 ### Functions
  10
  11 ```js
  12 /**
  13  * This is a function.
  14  *
  15  * @param {string} n - A string param
  16  * @return {string} A good string
  17  *
  18  * @example
  19  *
  20  *     foo('hello')
  21  */
  22
  23 function foo(n) {
  24   return n
  25 }
  26 ```
  27
  28 See: <https://jsdoc.app/index.html>
  29
  30 ### Types
  31
  32 | Type                            | Description                           |
  33 | ------------------------------- | ------------------------------------- |
  34 | `@param {string=} n`            | Optional                              |
  35 | `@param {string} [n]`           | Optional                              |
  36 | `@param {(string|number)} n`    | Multiple types                        |
  37 | `@param {*} n`                  | Any type                              |
  38 | `@param {...string} n`          | Repeatable arguments                  |
  39 | `@param {string} [n="hi"]`      | Optional with default                 |
  40 | `@param {string[]} n`           | Array of strings                      |
  41 | `@return {Promise<string[]>} n` | Promise fulfilled by array of strings |
  42
  43 See: <https://jsdoc.app/tags-type.html>
  44
  45 ### Variables
  46
  47 ```js
  48 /**
  49  * @type {number}
  50  */
  51 var FOO = 1
  52 ```
  53
  54 ```js
  55 /**
  56  * @const {number}
  57  */
  58 const FOO = 1
  59 ```
  60
  61 ### Typedef
  62
  63 ```js
  64 /**
  65  * A song
  66  * @typedef {Object} Song
  67  * @property {string} title - The title
  68  * @property {string} artist - The artist
  69  * @property {number} year - The year
  70  */
  71 ```
  72
  73 ```js
  74 /**
  75  * Plays a song
  76  * @param {Song} song - The {@link Song} to be played
  77  */
  78
  79 function play(song) {}
  80 ```
  81
  82 See: <https://jsdoc.app/tags-typedef.html>
  83
  84 ### Typedef Shorthand
  85
  86 {% raw %}
  87
  88 ```js
  89 /**
  90  * A song
  91  * @typedef {{title: string, artist: string, year: number}} Song
  92  */
  93 ```
  94
  95 {% endraw %}
  96
  97 ```js
  98 /**
  99  * Plays a song
 100  * @param {Song} song - The {@link Song} to be played
 101  */
 102
 103 function play(song) {}
 104 ```
 105
 106 See: <https://jsdoc.app/tags-typedef.html>
 107
 108 ### Importing types
 109
 110 ```js
 111 /**
 112  * @typedef {import('./Foo').default} Bar
 113  */
 114
 115 /**
 116  * @param {Bar} x
 117  */
 118
 119 function test(x) {}
 120 ```
 121
 122 This syntax is [TypeScript-specific](https://github.com/Microsoft/TypeScript/wiki/JsDoc-support-in-JavaScript#import-types).
 123
 124 ### Other keywords
 125
 126 ```js
 127 /**
 128  * @throws {FooException}
 129  * @private
 130  * @deprecated
 131  * @see
 132  *
 133  * @function
 134  * @class
 135  */
 136 ```
 137
 138 See the full list: <https://jsdoc.app/index.html#block-tags>
 139
 140 ### Renaming
 141
 142 ```js
 143 /*
 144  * @alias Foo.bar
 145  * @name Foo.bar
 146  */
 147 ```
 148
 149 Prefer `alias` over `name`. See: <https://jsdoc.app/tags-alias.html>