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 ### Importing types
  84
  85 ```js
  86 /**
  87  * @typedef {import('./Foo').default} Bar
  88  */
  89
  90 /**
  91  * @param {Bar} x
  92  */
  93
  94 function test(x) { }
  95 ```
  96
  97 This syntax is [TypeScript-specific](https://github.com/Microsoft/TypeScript/wiki/JsDoc-support-in-JavaScript#import-types).
  98
  99 ### Other keywords
 100
 101 ```js
 102 /**
 103  * @throws {FooException}
 104  * @private
 105  * @deprecated
 106  * @see
 107  *
 108  * @function
 109  * @class
 110  */
 111 ```
 112
 113 ### Renaming
 114
 115 ```js
 116 /*
 117  * @alias Foo.bar
 118  * @name Foo.bar
 119  */
 120 ```
 121
 122 Prefer `alias` over `name`. See: <http://usejsdoc.org/tags-alias.html>