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