jsDoc Évangélisation

TLDR ;

Travailler avec une base de code héritée - beaucoup d'entre nous ne sont pas capables d'esquiver de temps en temps - m'amène à essayer le jsDoc au lieu de Typescript. Je dois révéler la vérité surprenante !

Tout d'abord, nettoyons : jsDoc ou TS signifie simplement sous le temps du développeur (y compris la révision ultérieure, la réutilisation, regardez ce code dans n'importe quel environnement : page Web git, éditeur aléatoire, chrome, firefox, . ..:devtool, vim, cat ... );

Le premier mouvement

Ouvrez simplement votre éditeur, écrivez une remarque appropriée pour tester que jsDoc fonctionne ou non.

/** @typedef { 'JS' | 'JQuery' | 'TS' | 'jsDoc' } Phase; */

/**
 * On typing ' editor will popup string list.
 *
 * @type {Phase}
 */
const badCase = 'React'; // !!!! lint alert !!!!

/** @type {Phase} */
const goodCase = 'JQuery';

jsDoc contre Typescript

D'après mon expérience le jsDoc capable de remplacer le code TS, bonus le vortex entre ces deux existe.

La plus grande fonctionnalité de jsDoc à mon humble avis : elle utilise un système de commentaires JS standard, alors ne cassez aucun code JS, ce code s'exécutera partout où JS est capable de s'exécuter.

Expérience des éditeurs jsDoc

Je peux écrire jsDoc dans n'importe quel éditeur, mais rare est de le comprendre.

expérience du module de nœud

J'ai également créé un module npm : jsdoc-duck : un module codé en jsDoc. Cela a mis en évidence que sans TypeScript, il n'est pas possible de créer un module jsDoc npm. Peut-être que si je consacre plus de temps à déterminer les paramètres de construction rapide, une bonne solution pourra être trouvée. Mais la bonne nouvelle, si vous n'utilisez pas ce module avec npm, empruntez plutôt à notre code : copiez simplement index.js à un endroit - alors nous économisons l'usage d'insérer une nouvelle dépendance dans notre programme, et il ne se passe rien si le propriétaire du module transforme le module en autre chose.

Trou de ver entre jsDoc <-> Manuscrit

La bonne nouvelle, Typescript et jsDoc sont compatibles, seul le jsDoc utilise une syntaxe un peu différente. Mais vous pouvez utiliser les types de modules jsDoc dans un script dactylographié et vous pouvez également utiliser les types de modules dactylographiés dans le programme javascript / js jsDoc. La décision finale est donc entre vos mains.

Suivez la route de briques jaunes

Un exemple de code VS montre à quel point vos types ont été bien vus dans le code jsDoc, à mon avis, c'est surprenant, moins de bruit donne à votre code.

Prime

:: Extraits de code VS

/** @typedef { 'JS' | 'JQuery' | 'TS' | 'jsDoc' } Phase; */

/**
 * On typing ' editor will popup string list.
 *
 * @type {Phase}
 */
const badCase = 'React'; // !!!! lint alert !!!!

/** @type {Phase} */
const goodCase = 'JQuery';

:: code jsdoc-canard

(dans cette vue, la mise en évidence de la syntaxe n'aide pas à comprendre les types). Mais ce programme court est un bon exemple : jsDoc peut également utiliser les fonctionnalités avancées de TS.

  "@type": {
    "prefix": ["ty"],
    "body": ["/** @type {<pre class="brush:php;toolbar:false">import { useMemo, useReducer } from "react";

/**
 * @template T - Payload Type
 * @typedef {T extends { type: infer U, payload?: infer P } ? { type: U, payload?: P } : never} ActionType
 */

/** @template AM - Actions Map @typedef {{ [K in AM['type']]: K }} Labels */

/** @template AM - Actions Map @typedef {{ [T in AM["type"]]: Extract<AM, { type: T }> extends { payload: infer P } ? (payload: P) => void : () => void }} Quack */

/**
 * @template ST - State
 * @template AM - Actions Map
 * @typedef {(state: ST, action: AM) => ST} Reducer
 */

/**
 * Factory function to create a typed action map.
 * @template AM - Actions Map
 * @param {Labels<AM>} labelsObject - The keys representing action labels.
 * @param {function} dispatch - The dispatch function for actions.
 * @return {Quack<AM>} The resulting typed action map.
 */
export const quackFactory = (labelsObject, dispatch) => Object
  .keys(labelsObject)
  .reduce(
    /**
     * @arg {Quack<AM>} acc
     * @arg {keyof Labels<AM>} type
     * @return {Quack<AM>}
     */
    (acc, type) => ({
    ...acc,
    [type]: (payload) => {dispatch({ type, payload });}
  }), {});

/**
 * A factory hook to create a state and a typed dispatch functions\
 * @exports useDuck
 * @template AM - Actions Map
 * @template ST - State Typer
 * @param {(st: ST, action: AM) => ST} reducer - The reducer function to manage the state.
 * @param {ST} initialState - The initial state value.
 * @return {[ST, Quack<AM>]} The current state and a map of action dispatch functions.
 */
export const useDuck = (reducer, initialState, labels) => {
  const [state, dispatch] = useReducer(reducer, initialState);
  const quack = useMemo(
    () => quackFactory(labels, dispatch),
    [dispatch, labels]
  );
  return ([state, quack]);
};

bon codage, creuser à la place ajouter une dépendance

Ce qui précède est le contenu détaillé de. pour plus d'informations, suivez d'autres articles connexes sur le site Web de PHP en chinois!