docs: Améliorer la JSDoc.

regseb · Dec 21, 2024 · df0b55c · df0b55c
1 parent e114cea
commit df0b55c
Show file tree

Hide file tree

Showing 19 changed files with 134 additions and 112 deletions.
diff --git a/.metalint/eslint.config.js b/.metalint/eslint.config.js
@@ -1,5 +1,4 @@
 /**
- * @module
  * @license MIT
  * @author Sébastien Règne
  */

diff --git a/.metalint/eslint_config.config.js b/.metalint/eslint_config.config.js
@@ -1,9 +1,15 @@
 /**
- * @module
  * @license MIT
  * @author Sébastien Règne
  */
 
+/**
+ * @import { Linter } from "eslint"
+ */
+
+/**
+ * @type {Linter.Config}
+ */
 export default {
     rules: {
         // Plugin eslint-plugin-unicorn.

diff --git a/.metalint/eslint_node.config.js b/.metalint/eslint_node.config.js
@@ -1,9 +1,15 @@
 /**
- * @module
  * @license MIT
  * @author Sébastien Règne
  */
 
+/**
+ * @import { Linter } from "eslint"
+ */
+
+/**
+ * @type {Linter.Config}
+ */
 export default {
     rules: {
         // Suggestions.

diff --git a/.metalint/eslint_test.config.js b/.metalint/eslint_test.config.js
@@ -1,9 +1,15 @@
 /**
- * @module
  * @license MIT
  * @author Sébastien Règne
  */
 
+/**
+ * @import { Linter } from "eslint"
+ */
+
+/**
+ * @type {Linter.Config}
+ */
 export default {
     env: {
         mocha: true,

diff --git a/.metalint/markdownlint.config.js b/.metalint/markdownlint.config.js
@@ -1,11 +1,14 @@
 /**
- * @module
  * @license MIT
  * @author Sébastien Règne
  */
 
 /**
- * @type {import("markdownlint").Configuration}
+ * @import { ConfigurationStrict } from "markdownlint"
+ */
+
+/**
+ * @type {ConfigurationStrict}
  */
 export default {
     "heading-increment": true,

diff --git a/.metalint/metalint.config.js b/.metalint/metalint.config.js
@@ -1,9 +1,15 @@
 /**
- * @module
  * @license MIT
  * @author Sébastien Règne
  */
 
+/**
+ * @import { Config } from "metalint/types"
+ */
+
+/**
+ * @type {Config}
+ */
 export default {
     patterns: [
         "**",

diff --git a/.metalint/npm-package-json-lint.config.js b/.metalint/npm-package-json-lint.config.js
@@ -1,5 +1,4 @@
 /**
- * @module
  * @license MIT
  * @author Sébastien Règne
  */

diff --git a/.metalint/prantlf__jsonlint.config.js b/.metalint/prantlf__jsonlint.config.js
@@ -1,5 +1,4 @@
 /**
- * @module
  * @license MIT
  * @author Sébastien Règne
  */

diff --git a/.metalint/prettier.config.js b/.metalint/prettier.config.js
@@ -1,12 +1,18 @@
 /**
- * @module
  * @license MIT
  * @author Sébastien Règne
  */
 
 // @ts-ignore https://github.com/prettier/plugin-xml/issues/671
 import pluginXML from "@prettier/plugin-xml";
 
+/**
+ * @import { Config } from "prettier"
+ */
+
+/**
+ * @type {Config}
+ */
 export default {
     plugins: [pluginXML],
 

diff --git a/.metalint/prettier_javascript.config.js b/.metalint/prettier_javascript.config.js
@@ -1,9 +1,15 @@
 /**
- * @module
  * @license MIT
  * @author Sébastien Règne
  */
 
+/**
+ * @import { Config } from "prettier"
+ */
+
+/**
+ * @type {Config}
+ */
 export default {
     tabWidth: 4,
 };
diff --git a/.metalint/yaml-lint.config.js b/.metalint/yaml-lint.config.js
@@ -1,5 +1,4 @@
 /**
- * @module
  * @license MIT
  * @author Sébastien Règne
  */

diff --git a/.script/clean.js b/.script/clean.js
@@ -1,5 +1,4 @@
 /**
- * @module
  * @license MIT
  * @author Sébastien Règne
  */

diff --git a/.stryker.config.js b/.stryker.config.js
@@ -1,11 +1,14 @@
 /**
- * @module
  * @license MIT
  * @author Sébastien Règne
  */
 
 /**
- * @type {import("@stryker-mutator/api/core").PartialStrykerOptions}
+ * @import { PartialStrykerOptions } from "@stryker-mutator/api/core"
+ */
+
+/**
+ * @type {PartialStrykerOptions}
  */
 export default {
     disableTypeChecks: false,

diff --git a/src/at.js b/src/at.js
@@ -5,10 +5,10 @@
  */
 
 /**
- * La valeur maximale du délai accepté par <em>Node.js</em>.
+ * La valeur maximale du délai accepté par _Node.js_.
  *
  * @type {number}
- * @see https://nodejs.org/api/timers.html#setintervalcallback-delay-args
+ * @see https://nodejs.org/api/timers.html#settimeoutcallback-delay-args
  */
 const MAX_DELAY = 2_147_483_647;
 
@@ -47,13 +47,11 @@ export default class At {
      *                                     planifiée.
      * @param {Object}   [options]         Les options de la planification de la
      *                                     tâche.
-     * @param {any}      [options.thisArg] Le <code>this</code> utilisé pour la
-     *                                     fonction (la tâche planifiée par
-     *                                     défaut).
+     * @param {any}      [options.thisArg] Le `this` utilisé pour la fonction
+     *                                     (la tâche planifiée par défaut).
      * @param {any[]}    [options.args]    Les paramètres passés à la fonction
      *                                     (aucun paramètre par défaut).
-     * @throws {TypeError} Si le constructeur est appelé sans le mot clé
-     *                     <code>new</code>.
+     * @throws {TypeError} Si le constructeur est appelé sans le mot clé `new`.
      */
     constructor(date, func, options) {
         this.#date = date;

diff --git a/src/cron.js b/src/cron.js
@@ -8,64 +8,61 @@ import At from "./at.js";
 import CronExp from "./cronexp.js";
 
 /**
- * La classe d'une tâche <em>cronée</em>.
+ * La classe d'une tâche _cronée_.
  *
  * @class
  */
 export default class Cron {
     /**
-     * La liste des expressions <em>cron</em> indiquant les horaires d'exécution
-     * de la tâche.
+     * La liste des expressions _cron_ indiquant les horaires d'exécution de la
+     * tâche.
      *
      * @type {CronExp[]}
      */
     #cronexps;
 
     /**
-     * La fonction appelée à chaque horaire indiqué dans les expressions
-     * <em>cron</em>.
+     * La fonction appelée à chaque horaire indiqué dans les expressions _cron_.
      *
      * @type {Function}
      */
     #func;
 
     /**
-     * La planification de la prochaine exécution ; ou <code>undefined</code> si
-     * la tâche est désactivée.
+     * La planification de la prochaine exécution ; ou `undefined` si la tâche
+     * est désactivée.
      *
      * @type {At|undefined}
      */
     #at;
 
     /**
-     * Crée une tâche <em>cronée</em>.
+     * Crée une tâche _cronée_.
      *
-     * @param {string|string[]} cronex            La ou les expressions
-     *                                            <em>cron</em> indiquant les
-     *                                            horaires d'exécution de la
-     *                                            tâche.
+     * @param {string|string[]} cronex            La ou les expressions _cron_
+     *                                            indiquant les horaires
+     *                                            d'exécution de la tâche.
      * @param {Function}        func              La fonction appelée à chaque
      *                                            horaire indiqué dans les
-     *                                            expressions <em>cron</em>.
+     *                                            expressions _cron_.
      * @param {Object}          [options]         Les options de la tâche
-     *                                            <em>cronée</em>.
-     * @param {boolean}         [options.active]  <code>true</code> (par défaut)
-     *                                            pour activer la tâche ; sinon
-     *                                            <code>false</code>.
-     * @param {any}             [options.thisArg] Le <code>this</code> utilisé
-     *                                            pour la fonction (la tâche
-     *                                            <em>cronée</em> par défaut).
+     *                                            _cronée_.
+     * @param {boolean}         [options.active]  `true` (par défaut) pour
+     *                                            activer la tâche ; sinon
+     *                                            `false`.
+     * @param {any}             [options.thisArg] Le `this` utilisé pour la
+     *                                            fonction (la tâche _cronée_
+     *                                            par défaut).
      * @param {any[]}           [options.args]    Les paramètres passés à la
      *                                            fonction (aucun paramètre par
      *                                            défaut).
-     * @throws {Error}      Si la syntaxe d'une expression <em>cron</em> est
+     * @throws {Error}      Si la syntaxe d'une expression _cron_ est
      *                      incorrecte.
-     * @throws {RangeError} Si un intervalle d'une expression <em>cron</em> est
+     * @throws {RangeError} Si un intervalle d'une expression _cron_ est
      *                      invalide (hors limite ou quand la borne supérieure
      *                      est plus petite que la borne inférieure).
-     * @throws {TypeError}  Si le constructeur est appelé sans le mot clé
-     *                      <code>new</code> ou si un des paramètres n'a pas le
-     *                      bon type.
+     * @throws {TypeError}  Si le constructeur est appelé sans le mot clé `new`
+     *                      ou si un des paramètres n'a pas le bon type.
      */
     constructor(cronex, func, options) {
         this.#cronexps = Array.isArray(cronex)
@@ -84,8 +81,7 @@ export default class Cron {
     /**
      * Récupère l'état de la tâche (active ou non).
      *
-     * @returns {boolean} <code>true</code> si la tâche est active ; sinon
-     *                    <code>false</code>.
+     * @returns {boolean} `true` si la tâche est active ; sinon `false`.
      */
     get active() {
         return undefined !== this.#at;
@@ -94,8 +90,7 @@ export default class Cron {
     /**
      * Définit l'état de la tâche.
      *
-     * @param {boolean} value <code>true</code> pour activer la tâche ; sinon
-     *                        <code>false</code>.
+     * @param {boolean} value `true` pour activer la tâche ; sinon `false`.
      */
     set active(value) {
         if (value) {
@@ -125,8 +120,8 @@ export default class Cron {
     /**
      * Active la tâche.
      *
-     * @returns {boolean} <code>true</code> quand la tâche a été activée ;
-     *                    <code>false</code> si elle était déjà active.
+     * @returns {boolean} `true` quand la tâche a été activée ; `false` si elle
+     *                    était déjà active.
      */
     start() {
         if (undefined !== this.#at) {
@@ -139,8 +134,8 @@ export default class Cron {
     /**
      * Désactive la tâche.
      *
-     * @returns {boolean} <code>true</code> quand la tâche a été désactivée ;
-     *                    <code>false</code> si elle était déjà inactive.
+     * @returns {boolean} `true` quand la tâche a été désactivée ; `false` si
+     *                    elle était déjà inactive.
      */
     stop() {
         if (undefined === this.#at) {
@@ -152,20 +147,20 @@ export default class Cron {
     }
 
     /**
-     * Teste si une date respecte une des expressions <em>cron</em> de la tâche.
+     * Teste si une date respecte une des expressions _cron_ de la tâche.
      *
      * @param {Date} [date] La date qui sera testée (ou l'instant présent par
      *                      défaut).
-     * @returns {boolean} <code>true</code> si une des expressions est
-     *                    respectée ; sinon <code>false</code>.
+     * @returns {boolean} `true` si une des expressions est respectée ; sinon
+     *                    `false`.
      */
     test(date = new Date()) {
         return this.#cronexps.some((c) => c.test(date));
     }
 
     /**
-     * Calcule la prochaine date respectant une des expressions <em>cron</em> de
-     * la tâche.
+     * Calcule la prochaine date respectant une des expressions _cron_ de la
+     * tâche.
      *
      * @param {Date} [start] La date de début (ou l'instant présent par défaut).
      * @returns {Date} La prochaine date respectant une des expressions.