/wiki/TagParam.wiki

http://jsdoc-toolkit.googlecode.com/ · Unknown · 117 lines · 88 code · 29 blank · 0 comment · 0 complexity · 1f9719afed45c0baec80e54e1c363f3e MD5 · raw file

  1. #summary @param
  2. =The @param Tag=
  3. The param tag allows you to document information about the parameters to a function (such as constructors and methods).
  4. ==Syntax==
  5. {{{
  6. @param {paramType} paramName paramDescription
  7. }}}
  8. * paramType - Optional: the expected type of the parameter.
  9. * paramName - Required: the name of the parameter
  10. * paramDescription - Optional: a description associated with the parameter.
  11. ==Examples==
  12. {{{
  13. /**
  14. * @param userName The name of the user.
  15. */
  16. function logIn(userName) {
  17. // ...
  18. }
  19. }}}
  20. ===Basic===
  21. It 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.
  22. The most basic @param documentation simply provides the name of the parameter. This should match the parameter name in the function source code.
  23. {{{
  24. /**
  25. * @param userName
  26. */
  27. function logIn(userName) {
  28. // ...
  29. }
  30. }}}
  31. ===Parameter Type Information===
  32. Use curly-braces around the expected type of the parameter to document this information.
  33. {{{
  34. /**
  35. * @param {String} userName
  36. */
  37. function logIn(userName) {
  38. // ...
  39. }
  40. }}}
  41. Use a pipe symbol to document that multiple types are permitted.
  42. {{{
  43. /**
  44. * @param {String|Number} product
  45. */
  46. }}}
  47. Use the `[]` notation after a type to indicate an array of those types.
  48. {{{
  49. /**
  50. * @param {String[]} aliases
  51. */
  52. }}}
  53. ===Optional Parameters===
  54. Use square brackets around the parameter name to indicate that it is optional.
  55. {{{
  56. /**
  57. * @param {String} userName The user name to use when logging in.
  58. * @param {String} [accessLevel] The user accessLevel is optional.
  59. */
  60. function logIn(userName, accessLevel) {
  61. // ...
  62. }
  63. }}}
  64. ===Parameters With Default Values===
  65. 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).
  66. {{{
  67. /**
  68. * @param {String} userName The user name to use when logging in.
  69. * @param {String} [accessLevel="author"] The user accessLevel is optional.
  70. */
  71. function logIn(userName, accessLevel) {
  72. // ...
  73. }
  74. }}}
  75. ===Parameters With Properties===
  76. If a parameter is expected to have a particular property, you can document that immediately after the `@param` tag for that parameter, like so:
  77. {{{
  78. /**
  79. * @param userInfo Information about the user.
  80. * @param userInfo.name The name of the user.
  81. * @param userInfo.email The email of the user.
  82. */
  83. function logIn(userInfo) {
  84. doLogIn(userInfo.name, userInfo.email);
  85. }
  86. }}}
  87. ==See Also==
  88. * How to document parameters using [InlineDocs Inline Documentation]