diff --git a/STYLE.md b/STYLE.md index 7a9fe40deed9..bd044ba93e61 100644 --- a/STYLE.md +++ b/STYLE.md @@ -222,12 +222,21 @@ Use `lodashGet()` to safely access object properties and `||` to short circuit n ``` ## JSDocs -- Avoid docs that don't add any additional information. + - Always document parameters and return values. -- Method descriptions are optional and should be added when it's not obvious what the purpose of the method is. -- Use uppercase when referring to JS primitive values (e.g. `Boolean` not `bool`, `Number` not `int`, etc) +- Optional parameters should be enclosed by `[]` e.g. `@param {String} [optionalText]`. +- Document object parameters with separate lines e.g. `@param {Object} parameters` followed by `@param {String} parameters.field`. +- If a parameter accepts more than one type use `*` to denote there is no single type. +- Use uppercase when referring to JS primitive values (e.g. `Boolean` not `bool`, `Number` not `int`, etc). - When specifying a return value use `@returns` instead of `@return`. If there is no return value do not include one in the doc. +- Avoid descriptions that don't add any additional information. Method descriptions should only be added when it's behavior is unclear. +- Do not use block tags other than `@param` and `@returns` (e.g. `@memberof`, `@constructor`, etc). +- Do not document default parameters. They are already documented by adding them to a declared function's arguments. +- Do not use record types e.g. `{Object.}`. +- Do not create `@typedef` to use in JSDocs. +- Do not use type unions e.g. `{(number|boolean)}`. + ```javascript // Bad /**