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.

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

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

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

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!