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
  40 See: <http://usejsdoc.org/tags-type.html>
  41
  42 ### Variables
  43
  44 ```js
  45 /**
  46  * @type {number}
  47  */
  48 var FOO = 1
  49 ```
  50
  51 ```js
  52 /**
  53  * @const {number}
  54  */
  55 const FOO = 1
  56 ```
  57
  58 ### Typedef
  59
  60 ```js
  61 /**
  62  * A song
  63  * @typedef {Object} Song
  64  * @property {string} title - The title
  65  * @property {string} artist - The artist
  66  * @property {number} year - The year
  67  */
  68 ```
  69
  70 ```js
  71 /**
  72  * Plays a song
  73  * @param {Song} song - The {@link Song} to be played
  74  */
  75
  76 function play (song) {
  77 }
  78 ```
  79
  80 See: <http://usejsdoc.org/tags-typedef.html>
  81
  82 ### Importing types
  83
  84 ```js
  85 /**
  86  * @typedef {import('./Foo').default} Bar
  87  */
  88
  89 /**
  90  * @param {Bar} x
  91  */
  92
  93 function test(x) { }
  94 ```
  95
  96 This syntax is [TypeScript-specific](https://github.com/Microsoft/TypeScript/wiki/JsDoc-support-in-JavaScript#import-types).
  97
  98 ### Other keywords
  99
 100 ```js
 101 /**
 102  * @throws {FooException}
 103  * @private
 104  * @deprecated
 105  * @see
 106  *
 107  * @function
 108  * @class
 109  */
 110 ```
 111
 112 ### Renaming
 113
 114 ```js
 115 /*
 116  * @alias Foo.bar
 117  * @name Foo.bar
 118  */
 119 ```
 120
 121 Prefer `alias` over `name`. See: <http://usejsdoc.org/tags-alias.html>