From 4d990f61d78625a47b1019cd1fdea2d73c69041a Mon Sep 17 00:00:00 2001 From: Marc Glasser Date: Wed, 12 Jan 2022 09:46:05 -1000 Subject: [PATCH 1/4] Improve guidance for JSDocs --- STYLE.md | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/STYLE.md b/STYLE.md index 7a9fe40deed9..bbfc85676d68 100644 --- a/STYLE.md +++ b/STYLE.md @@ -222,10 +222,16 @@ Use `lodashGet()` to safely access object properties and `||` to short circuit n ``` ## JSDocs -- Avoid docs that don't add any additional information. +- Avoid docs that don't add any additional information. Method descriptions should only be added when it's not obvious what the purpose of the method is by name or from looking at the code. - 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) +- Avoid using block tags other than `@param` and `@returns` (e.g. `@memberof`, `@constructor`, etc). +- Optional parameters should be enclosed by `[]` e.g. `@param {String} [optionalText]`. +- Do not document default parameters. They are already documented by adding them to a declared function's arguments. +- Document object parameters with separate lines e.g. `@param {Object} parameters` followed by `@param {String} parameters.field`. +- Do not document object parameters with record types e.g. `{Object.}`. +- Do not create `@typedef` to use in JSDocs. +- If a parameter accepts more than one type use `*` to denote there is no single type. Do not use a type union e.g. `{(number|boolean)}`. +- 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. ```javascript From 85761fcc2eca4123a9a44e4a2291c68ee7320f3c Mon Sep 17 00:00:00 2001 From: Marc Glasser Date: Wed, 12 Jan 2022 09:49:11 -1000 Subject: [PATCH 2/4] abbreviate --- STYLE.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/STYLE.md b/STYLE.md index bbfc85676d68..ca60193d5aa1 100644 --- a/STYLE.md +++ b/STYLE.md @@ -222,13 +222,13 @@ Use `lodashGet()` to safely access object properties and `||` to short circuit n ``` ## JSDocs -- Avoid docs that don't add any additional information. Method descriptions should only be added when it's not obvious what the purpose of the method is by name or from looking at the code. - Always document parameters and return values. +- Avoid docs that don't add any additional information. Method descriptions should only be added when it's behavior is unclear. - Avoid using block tags other than `@param` and `@returns` (e.g. `@memberof`, `@constructor`, etc). - Optional parameters should be enclosed by `[]` e.g. `@param {String} [optionalText]`. - Do not document default parameters. They are already documented by adding them to a declared function's arguments. - Document object parameters with separate lines e.g. `@param {Object} parameters` followed by `@param {String} parameters.field`. -- Do not document object parameters with record types e.g. `{Object.}`. +- Do not use record types e.g. `{Object.}`. - Do not create `@typedef` to use in JSDocs. - If a parameter accepts more than one type use `*` to denote there is no single type. Do not use a type union e.g. `{(number|boolean)}`. - Use uppercase when referring to JS primitive values (e.g. `Boolean` not `bool`, `Number` not `int`, etc). From 3bba28423c6d63f5a74f6497f74d2185fb4b37ac Mon Sep 17 00:00:00 2001 From: Marc Glasser Date: Wed, 12 Jan 2022 12:30:46 -1000 Subject: [PATCH 3/4] split up dos and donts --- STYLE.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/STYLE.md b/STYLE.md index ca60193d5aa1..0937c317a81a 100644 --- a/STYLE.md +++ b/STYLE.md @@ -222,18 +222,20 @@ Use `lodashGet()` to safely access object properties and `||` to short circuit n ``` ## JSDocs + - Always document parameters and return values. -- Avoid docs that don't add any additional information. Method descriptions should only be added when it's behavior is unclear. -- Avoid using block tags other than `@param` and `@returns` (e.g. `@memberof`, `@constructor`, etc). - Optional parameters should be enclosed by `[]` e.g. `@param {String} [optionalText]`. -- Do not document default parameters. They are already documented by adding them to a declared function's arguments. - Document object parameters with separate lines e.g. `@param {Object} parameters` followed by `@param {String} parameters.field`. -- Do not use record types e.g. `{Object.}`. -- Do not create `@typedef` to use in JSDocs. - If a parameter accepts more than one type use `*` to denote there is no single type. Do not use a type union e.g. `{(number|boolean)}`. - 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. + ```javascript // Bad /** From c260bdf1f08cb5966aeb81f2e8eeca3b2d3a92aa Mon Sep 17 00:00:00 2001 From: Marc Glasser Date: Wed, 12 Jan 2022 12:32:22 -1000 Subject: [PATCH 4/4] split last dont out --- STYLE.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/STYLE.md b/STYLE.md index 0937c317a81a..bd044ba93e61 100644 --- a/STYLE.md +++ b/STYLE.md @@ -226,7 +226,7 @@ Use `lodashGet()` to safely access object properties and `||` to short circuit n - Always document parameters and return values. - 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. Do not use a type union e.g. `{(number|boolean)}`. +- 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. @@ -235,6 +235,7 @@ Use `lodashGet()` to safely access object properties and `||` to short circuit n - 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