jsdoc.md

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