jsDoc Evangelisation

TLDR;

Das Arbeiten mit einer alten Codebasis – viele von uns können nicht von Zeit zu Zeit ausweichen – veranlasste mich, jsDoc anstelle von Typescript auszuprobieren. Ich muss die überraschende Wahrheit enthüllen!

Lassen Sie uns zunächst alles bereinigen: jsDoc oder TS bedeutet nur „unter Entwicklerzeit“ (einschließlich späterer Überprüfung, Wiederverwendung, betrachten Sie diesen Code in jeder Umgebung: Git-Webseite, Zufallseditor, Chrome, Firefox, . ..:devtool, vim, cat ... );

Der erste Satz

Öffnen Sie einfach Ihren Editor und schreiben Sie eine entsprechende Bemerkung, um zu testen, ob jsDoc funktioniert oder nicht.

/** @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 vs. Typescript

Meiner Erfahrung nach kann der jsDoc den TS-Code ersetzen, außerdem existiert das Wurmloch zwischen diesen beiden.

Die größte jsDoc-Funktion meiner Meinung nach: Hierbei wird ein standardmäßiges JS-Kommentarsystem verwendet, also brechen Sie keinen JS-Code, dieser Code wird überall dort ausgeführt, wo JS ausgeführt werden kann.

Erfahrung von jsDoc-Editoren

Ich kann jsDoc in jedem Editor schreiben, aber selten verstehe ich es.

Erfahrung mit Knotenmodulen

Ich habe auch ein npm-Modul erstellt: jsdoc-duck: ein jsDoc-codiertes Modul. Dies verdeutlichte, dass es ohne TypeScript nicht möglich ist, ein jsDoc-npm-Modul zu erstellen. Vielleicht kann ich eine richtige Lösung finden, wenn ich mehr Zeit damit verbringe, die Parameter für den Hausbau herauszufinden. Aber die gute Nachricht: Wenn Sie dieses Modul nicht mit npm verwenden, sondern stattdessen auf unseren Code zurückgreifen: Kopieren Sie einfach index.js an einen Ort – dann können wir sicher eine neue Abhängigkeit in unser Programm einfügen, und es passiert nichts Wenn der Modulbesitzer das Modul auf etwas anderes umstellt.

Wurmloch zwischen jsDoc <-> Typoskript

Die gute Nachricht ist, dass Typescript und jsDoc miteinander kompatibel sind, nur dass jsDoc eine etwas andere Syntax verwendet. Sie können jedoch jsDoc-Modultypen in Typescripts verwenden und Sie können Typescript-Modultypen auch in Javascript/js jsDoc-Programmen verwenden. Die endgültige Entscheidung liegt also in Ihrer Hand.

Folgen Sie der gelben Backsteinstraße

VS-Codebeispiele zeigen, wie gut Ihre Typen im jsDoc-Code angezeigt werden. Meiner Meinung nach verursacht dies überraschend weniger Lärm in Ihrem Code.

Bonus

:: VS-Code-Schnipsel

/** @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-duck-Code

(In dieser Ansicht hilft die Hervorhebung der Syntax nicht dabei, die Typen zu verstehen.) Aber dieses kurze Programm ist ein gutes Beispiel dafür, dass jsDoc auch die erweiterten TS-Funktionen nutzen kann.

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

Viel Spaß beim Codieren, wühlen statt Abhängigkeit hinzufügen

Das obige ist der detaillierte Inhalt vonjsDoc Evangelisation. Für weitere Informationen folgen Sie bitte anderen verwandten Artikeln auf der PHP chinesischen Website!