docs(transformers): Slightly improve JSDoc

Inist-CNRS · Jul 23, 2021 · 59bc7f5 · 59bc7f5
1 parent 7ade53d
commit 59bc7f5
Show file tree

Hide file tree

Showing 32 changed files with 342 additions and 177 deletions.
diff --git a/docs/plugin-transformers.md b/docs/plugin-transformers.md
diff --git a/packages/transformers/README.md b/packages/transformers/README.md
diff --git a/packages/transformers/src/dollar-array.js b/packages/transformers/src/dollar-array.js
@@ -9,9 +9,32 @@ import dollar from './dollar';
  * ```ini
  * [$ARRAY]
  * field = keywords
+ *
+ * [exchange]
+ * value = omit('$origin')
+ * ```
+ *
+ * Entrée:
+ *
+ * ```json
+ * [{
+ *   "keywords": "un"
+ * }, {
+ *   "keywords": "deux"
+ * }]
+ * ```
+ *
+ * Sortie:
+ *
+ * ```json
+ * [{
+ *   "keywords": ["un"]
+ * }, {
+ *   "keywords": ["deux"]
+ * }]
  * ```
  *
- * @param {String} [field] field path to apply the transformation
+ * @param {String} field field path to apply the transformation
  * @returns {Object}
  */
 export default function $ARRAY(data, feed) {

diff --git a/packages/transformers/src/dollar-boolean.js b/packages/transformers/src/dollar-boolean.js
@@ -9,9 +9,42 @@ import dollar from './dollar';
  * ```ini
  * [$BOOLEAN]
  * field = haveMoney
+ *
+ * [exchange]
+ * value = omit('$origin')
+ * ```
+ *
+ * Entrée:
+ *
+ * ```json
+ * [{
+ *   "name": "Chuck",
+ *   "haveMoney": 10000
+ * }, {
+ *   "name": "Charlot",
+ *   "haveMoney": "yes"
+ * }, {
+ *   "name": "Alan",
+ *   "haveMoney": 1
+ * }]
+ * ```
+ *
+ * Sortie:
+ *
+ * ```json
+ * [{
+ *   "name": "Chuck",
+ *   "haveMoney": false
+ * }, {
+ *   "name": "Charlot",
+ *   "haveMoney": true
+ * }, {
+ *   "name": "Alan",
+ *   "haveMoney": true
+ * }]
  * ```
  *
- * @param {String} [field] field path to apply the transformation
+ * @param {String} field field path to apply the transformation
  * @returns {Object}
  */
 export default function $BOOLEAN(data, feed) {

diff --git a/packages/transformers/src/dollar-column.js b/packages/transformers/src/dollar-column.js
@@ -11,8 +11,9 @@ import dollar from './dollar';
  * field = newTitle
  * column = oldTitle
  * ```
- * @param {String} [field] field path to apply the transformation
- * @param {String} [column] value to use during the transformation
+ *
+ * @param {String} field    field path to apply the transformation
+ * @param {String} column   value to use during the transformation
  * @returns {Object}
  */
 export default function $COLUMN(data, feed) {

diff --git a/packages/transformers/src/dollar-concat-uri.js b/packages/transformers/src/dollar-concat-uri.js
@@ -2,7 +2,7 @@ import transformer from './operations/CONCAT_URI';
 import dollar from './dollar';
 
 /**
- * compoer un identifiant avec plusieurs champs
+ * composer un identifiant avec plusieurs champs
  *
  * Exemple :
  *
@@ -13,9 +13,10 @@ import dollar from './dollar';
  * column = prenom
  * separator = -
  * ```
- * @param {String} [field] field path to get the result of the transformation
- * @param {String} [column] field path to get data
- * @param {String} [separator] glue between each column
+ *
+ * @param {String} field    field path to get the result of the transformation
+ * @param {String} column   field path to get data
+ * @param {String} separator glue between each column
  * @returns {Object}
  */
 export default function $CONCAT_URI(data, feed) {

diff --git a/packages/transformers/src/dollar-concat.js b/packages/transformers/src/dollar-concat.js
@@ -13,8 +13,8 @@ import dollar from './dollar';
  * columns = part2
  * ```
  *
- * @param {String} [field] field path to get the result of the transformation
- * @param {String} [columns] field path to get value
+ * @param {String} field    field path to get the result of the transformation
+ * @param {String} columns  field path to get value
  * @returns {Object}
  */
 export default function $CONCAT(data, feed) {

diff --git a/packages/transformers/src/dollar-default.js b/packages/transformers/src/dollar-default.js
@@ -12,8 +12,8 @@ import dollar from './dollar';
  * alternative = not available
  * ```
  *
- * @param {String} [field] field path to apply the transformation
- * @param {String} [alternative] value to use if field does not exist
+ * @param {String} field    field path to apply the transformation
+ * @param {String} alternative value to use if field does not exist
  * @returns {Object}
  */
 export default function $DEFAULT(data, feed) {

diff --git a/packages/transformers/src/dollar-format.js b/packages/transformers/src/dollar-format.js
@@ -10,8 +10,8 @@ import dollar from './dollar';
  * with = (%s:%s)
  * ```
  *
- * @param {String} [field] field path to get data source (must be an array)
- * @param {String} [with] template string like sprintf
+ * @param {String} field    field path to get data source (must be an array)
+ * @param {String} with     template string like sprintf
  * @returns {Object}
  */
 export default function $FORMAT(data, feed) {

diff --git a/packages/transformers/src/dollar-get.js b/packages/transformers/src/dollar-get.js
@@ -2,7 +2,7 @@ import transformer from './operations/GET';
 import dollar from './dollar';
 
 /**
- * Récupére toutes les valeurs correspondant à un chemin (dot path)
+ * Récupère toutes les valeurs correspondant à un chemin (dot path)
  *
  *  Exemple :
  *
@@ -12,8 +12,8 @@ import dollar from './dollar';
  * path = input
  * ```
  *
- * @param {String} [field] field path to get the result of the transformation
- * @param {String} [path] field path to get value
+ * @param {String} field    field path to get the result of the transformation
+ * @param {String} path     field path to get value
  * @returns {Object}
  */
 export default function $GET(data, feed) {

diff --git a/packages/transformers/src/dollar-join.js b/packages/transformers/src/dollar-join.js
@@ -12,8 +12,8 @@ import dollar from './dollar';
  * path = input
  * ```
  *
- * @param {String} [field] field path to apply the transformation (must be an array)
- * @param {String} [separator] glue between each field
+ * @param {String} field     field path to apply the transformation (must be an array)
+ * @param {String} separator glue between each field
  * @returns {Object}
  */
 export default function $JOIN(data, feed) {

diff --git a/packages/transformers/src/dollar-lowercase.js b/packages/transformers/src/dollar-lowercase.js
@@ -11,7 +11,7 @@ import dollar from './dollar';
  * field = title
  * ```
  *
- * @param {String} [field] field path to apply the transformation
+ * @param {String} field field path to apply the transformation
  * @returns {Object}
  */
 export default function $LOWERCASE(data, feed) {

diff --git a/packages/transformers/src/dollar-mapping.js b/packages/transformers/src/dollar-mapping.js
@@ -3,7 +3,7 @@ import dollar from './dollar';
 
 /**
  * Opération permettant le remplacement à partir d'une table
- * (équivalent à l'enchaînement de plusieurs opération REPLACE)
+ * (équivalent à l'enchaînement de plusieurs opérations {@link $REPLACE})
  *
  * Exemple :
  *
@@ -13,8 +13,8 @@ import dollar from './dollar';
  * list = "hello":"bonjour", "hi":"salut"
  * ```
  *
- * @param {String} [field] field path to apply the transformation
- * @param {String} [list] the mapping list
+ * @param {String} field    field path to apply the transformation
+ * @param {String} list     the mapping list
  * @returns {Object}
  */
 export default function $MAPPING(data, feed) {

diff --git a/packages/transformers/src/dollar-mask.js b/packages/transformers/src/dollar-mask.js
@@ -12,8 +12,8 @@ import dollar from './dollar';
  * with = ^[a-z]+$
  * ```
  *
- * @param {String} [path] field path to apply the control
- * @param {String} [value] value to use during the transformation
+ * @param {String} path field path to apply the control
+ * @param {String} with regular expression to check
  * @returns {Object}
  */
 export default function $MASK(data, feed) {

diff --git a/packages/transformers/src/dollar-number.js b/packages/transformers/src/dollar-number.js
@@ -10,8 +10,8 @@ import dollar from './dollar';
  * [$NUMBER]
  * field = counter
  * ```
- * 
- * @param {String} [feild] field path to apply the transformation
+ *
+ * @param {String} field field path to apply the transformation
  * @returns {Object}
  */
 export default function $NUMBER(data, feed) {

diff --git a/packages/transformers/src/dollar-parse.js b/packages/transformers/src/dollar-parse.js
@@ -11,7 +11,7 @@ import dollar from './dollar';
  * field = json
  * ```
  *
- * @param {String} [field] field path to apply the transformation
+ * @param {String} field field path to apply the transformation
  * @returns {Object}
  */
 export default function $PARSE(data, feed) {

diff --git a/packages/transformers/src/dollar-prefix.js b/packages/transformers/src/dollar-prefix.js
@@ -12,8 +12,8 @@ import dollar from './dollar';
  * with = #
  * ```
  *
- * @param {String} [field] field path to apply the transformation
- * @param {String} [vith] value to add at the begining of the field
+ * @param {String} field field path to apply the transformation
+ * @param {String} with  value to add at the begining of the field
  * @returns {Object}
  */
 export default function $PREFIX(data, feed) {

diff --git a/packages/transformers/src/dollar-remove.js b/packages/transformers/src/dollar-remove.js
@@ -12,8 +12,8 @@ import dollar from './dollar';
  * the = .
  * ```
  *
- * @param {String} [path] field path to apply the transformation
- * @param {String} [the] value todrop in the field
+ * @param {String} path field path to apply the transformation
+ * @param {String} the  value to drop in the field
  * @returns {Object}
  */
 export default function $REMOVE(data, feed) {

diff --git a/packages/transformers/src/dollar-replace-regex.js b/packages/transformers/src/dollar-replace-regex.js
@@ -11,12 +11,11 @@ import dollar from './dollar';
  * field = title
  * searchValue = $hel\w+
  * replaceValue = bonjour
- *
  * ```
  *
- * @param {String} [field] field path to apply the transformation
- * @param {String} [searchValue] regex to search
- * @param {String} [replaceValue] value to replace with
+ * @param {String} field        field path to apply the transformation
+ * @param {String} searchValue  regex to search
+ * @param {String} replaceValue value to replace with
  * @returns {Object}
  */
 export default function $REPLACE_REGEX(data, feed) {

diff --git a/packages/transformers/src/dollar-replace.js b/packages/transformers/src/dollar-replace.js
@@ -11,12 +11,11 @@ import dollar from './dollar';
  * field = title
  * searchValue = 1
  * replaceValue = un
- *
  * ```
  *
- * @param {String} [field] field path to apply the transformation
- * @param {String} [searchValue] value to search
- * @param {String} [replaceValue] value to replace with
+ * @param {String} field        field path to apply the transformation
+ * @param {String} searchValue  value to search
+ * @param {String} replaceValue value to replace with
  * @returns {Object}
  */
 export default function $REPLACE(data, feed) {

diff --git a/packages/transformers/src/dollar-select.js b/packages/transformers/src/dollar-select.js
@@ -2,19 +2,18 @@ import transformer from './operations/SELECT';
 import dollar from './dollar';
 
 /**
- * Prendre une valeir dans un objet à partir de son chemin (dot path)
+ * Prendre une valeur dans un objet à partir de son chemin (dot path)
  *
  * Exemple :
  *
  * ```ini
  * [$SELECT]
  * field = title
- * path
- *
+ * path = en
  * ```
  *
- * @param {String} [field] field path to get the result of the selection
- * @param {String} [path] field path to get value
+ * @param {String} field field path to get the result of the selection
+ * @param {String} path  field path to get value
  * @returns {Object}
  */
 export default function $SELECT(data, feed) {

diff --git a/packages/transformers/src/dollar-shift.js b/packages/transformers/src/dollar-shift.js
@@ -12,8 +12,8 @@ import dollar from './dollar';
  * gap = 2
  * ```
  *
- * @param {String} [path] field path to apply the transformation
- * @param {String} [gap] how many item or characters to drop
+ * @param {String} path field path to apply the transformation
+ * @param {String} gap  how many items or characters to drop
  * @returns {Object}
  */
 export default function $SHIFT(data, feed) {

diff --git a/packages/transformers/src/dollar-split.js b/packages/transformers/src/dollar-split.js
@@ -10,11 +10,10 @@ import dollar from './dollar';
  * [$SPLIT]
  * field = title
  * separator = |
- *
  * ```
  *
- * @param {String} [field] field path to apply the transformation
- * @param {String} [separator] value to use to split the field
+ * @param {String} field     field path to apply the transformation
+ * @param {String} separator value to use to split the field
  * @returns {Object}
  */
 export default function $SPLIT(data, feed) {

diff --git a/packages/transformers/src/dollar-string.js b/packages/transformers/src/dollar-string.js
@@ -11,7 +11,7 @@ import dollar from './dollar';
  * field = title
  * ```
  *
- * @param {String} [field] field path to apply the transformation
+ * @param {String} field field path to apply the transformation
  * @returns {Object}
  */
 export default function $STRING(data, feed) {

diff --git a/packages/transformers/src/dollar-suffix.js b/packages/transformers/src/dollar-suffix.js
@@ -12,8 +12,8 @@ import dollar from './dollar';
  * with = !
  * ```
  *
- * @param {String} [field] field path to apply the transformation
- * @param {String} [with] value to add at the end of the field
+ * @param {String} field field path to apply the transformation
+ * @param {String} with  value to add at the end of the field
  * @returns {Object}
  */
 export default function $SUFFIX(data, feed) {

diff --git a/packages/transformers/src/dollar-trim.js b/packages/transformers/src/dollar-trim.js
@@ -11,7 +11,7 @@ import dollar from './dollar';
  * field = title
  * ```
  *
- * @param {String} [field] field path to apply the transformation
+ * @param {String} field field path to apply the transformation
  * @returns {Object}
  */
 export default function $TRIM(data, feed) {

diff --git a/packages/transformers/src/dollar-truncate-words.js b/packages/transformers/src/dollar-truncate-words.js
@@ -3,7 +3,7 @@ import dollar from './dollar';
 
 /**
  * Opération permettant la troncature par nombre de mots
- * et non pas par nombre de caractères comme pour opération TRUNCATE
+ * et non pas par nombre de caractères comme pour l'opération {@link $TRUNCATE}
  *
  * Exemple :
  *

diff --git a/packages/transformers/src/dollar-truncate.js b/packages/transformers/src/dollar-truncate.js
@@ -10,11 +10,10 @@ import dollar from './dollar';
  * [$TRUNCATE]
  * field = title
  * gap = 25
- *
  * ```
  *
- * @param {String} [field] field path to apply the transformation
- * @param {String} [gap] how many items or characters to keep
+ * @param {String} field field path to apply the transformation
+ * @param {String} gap   how many items or characters to keep
  * @returns {Object}
  */
 export default function $TRUNCATE(data, feed) {