/wiki/TagParam.wiki

  1#summary @param
  2
  3=The @param Tag=
  4
  5The param tag allows you to document information about the parameters to a function (such as constructors and methods).
  6
  7==Syntax==
  8
  9{{{
 10@param {paramType} paramName paramDescription
 11}}}
 12
 13  * paramType - Optional: the expected type of the parameter.
 14  * paramName - Required: the name of the parameter
 15  * paramDescription - Optional: a description associated with the parameter.
 16
 17==Examples==
 18
 19{{{
 20/**
 21 * @param userName The name of the user.
 22 */
 23 function logIn(userName) {
 24 	// ...
 25 }
 26}}}
 27
 28===Basic===
 29
 30It is not technically required for you to use the @param tag since !JsDoc Toolkit will parse your function declarations and automatically find the parameter names for you. However it is useful to use @param tags to provide type information, and descriptive text.
 31
 32The most basic @param documentation simply provides the name of the parameter. This should match the parameter name in the function source code.
 33
 34{{{
 35/**
 36 * @param userName
 37 */
 38 function logIn(userName) {
 39 	// ...
 40 }
 41}}}
 42
 43===Parameter Type Information===
 44
 45Use curly-braces around the expected type of the parameter to document this information.
 46
 47 {{{
 48 /**
 49  * @param {String} userName
 50  */
 51 function logIn(userName) {
 52 	// ...
 53 }
 54}}}
 55
 56Use a pipe symbol to document that multiple types are permitted.
 57
 58{{{
 59 /**
 60  * @param {String|Number} product
 61  */
 62}}}
 63
 64Use the `[]` notation after a type to indicate an array of those types.
 65
 66{{{
 67 /**
 68  * @param {String[]} aliases
 69  */
 70}}}
 71
 72===Optional Parameters===
 73
 74 Use square brackets around the parameter name to indicate that it is optional.
 75
 76{{{
 77 /**
 78  * @param {String} userName The user name to use when logging in.
 79  * @param {String} [accessLevel] The user accessLevel is optional.
 80  */
 81 function logIn(userName, accessLevel) {
 82 	// ...
 83 }
 84}}}
 85
 86===Parameters With Default Values===
 87
 88 A parameter that can have a default value must be optional, so use square brackets around the parameter name to indicate that it is optional. Add an equals sign immediately after the parameter name to provide information about the default value. Note that the string you give for the default value is literally displayed in the documentation (any !JavaScript you put there will not be evaluated).
 89
 90{{{
 91 /**
 92  * @param {String} userName The user name to use when logging in.
 93  * @param {String} [accessLevel="author"] The user accessLevel is optional.
 94  */
 95 function logIn(userName, accessLevel) {
 96 	// ...
 97 }
 98}}}
 99
100===Parameters With Properties===
101
102 If a parameter is expected to have a particular property, you can document that immediately after the `@param` tag for that parameter, like so:
103
104{{{
105 /**
106  * @param userInfo Information about the user.
107  * @param userInfo.name The name of the user.
108  * @param userInfo.email The email of the user.
109  */
110 function logIn(userInfo) {
111 	doLogIn(userInfo.name, userInfo.email);
112 }
113}}}
114
115==See Also==
116
117  * How to document parameters using [InlineDocs Inline Documentation]