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.

feature	jsDoc	Typescript
compiling freedom	Do not need compiling the code.	mandatory to compile
dependency freedom	Can working without any dependency	at least TS is your dependency
namespace freedom	Don't interfere Types and other imports names. You can use same name of component and component Type in React for example.	Typesript names are identical including as any other referenct
rework freedom	Don't need to change existing code, just insert a comment.	at least some part in your code need to be turn to TS
legacy freedom	Can be use even transform to Typescript the project is not option. Many legacy projects affected this situation.	need to push management to allow that modification
Maximalism freedom	Don't need to use every where. Even you can use on a new commits, and after easy to search which is the new or reworked parts.	also enough to turn build system, and just part of code to TS
future freedom	Later can easy trasnlate to TS. Under the hood this is use same technic, just different way.	need to work if decide to use JS instead TS
mindset freedom	Because this is a comment your know well this is don't made any type check at runtime for you as TS also.	TS is noising your code

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]);
};

} */"], "description": "jsdoc type" }, "@typedef": { "prefix": ["td"], "body": ["/** @typedef {} Foo */"], "description": "jsdoc typedef" },

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!