jsDoc Penginjilan

TLDR;

Kerja dengan asas kod lama - ramai di antara kita tidak dapat mengelak dari semasa ke semasa - bawa saya mencuba jsDoc dan bukannya Typescript. Saya perlu mendedahkan kebenaran yang mengejutkan!

Pertama sekali mari kita bersihkan: jsDoc atau TS hanya bermaksud di bawah masa pembangun (termasuk semakan kemudian, penggunaan semula, lihat kod itu dalam mana-mana persekitaran: halaman web git, editor rawak, chrome, firefox, . ..:devtool, vim, cat ... );

Pergerakan Pertama

Buka sahaja editor anda, tulis kenyataan yang betul untuk menguji jsDoc berfungsi atau tidak.

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

Dalam pengalaman saya, jsDoc dapat menggantikan kod TS, bonus lubang cacing antara kedua-dua ini wujud.

Ciri jsDoc terbesar imho: ini menggunakan sistem ulasan JS standard, jadi jangan pecahkan sebarang kod JS, kod ini akan dijalankan di mana-mana tempat di mana JS mampu dijalankan.

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

pengalaman editor jsDoc

Saya boleh menulis jsDoc dalam mana-mana editor, tetapi jarang yang memahaminya.

pengalaman modul nod

Saya juga mencipta modul npm: jsdoc-duck: modul berkod jsDoc. Ini menyerlahkan bahawa tanpa TypeScript, adalah tidak mungkin untuk mencipta modul npm jsDoc. Mungkin jika saya menghabiskan lebih banyak masa untuk mengetahui parameter bangunan vite maka boleh didapati penyelesaian yang tepat. Tetapi berita baiknya, jika tidak menggunakan modul itu dengan npm, sebaliknya meminjam ke kod kami: hanya salin index.js ke tempat - kemudian kami menyimpan penggunaan untuk memasukkan kebergantungan baharu pada program kami, dan jangan berlaku apa-apa jika pemilik modul menukar modul kepada sesuatu yang lain.

Lubang cacing antara jsDoc <-> Skrip taip

Berita baiknya Typescript dan jsDoc adalah serasi antara satu sama lain, cuma jsDoc menggunakan sintaks yang sedikit berbeza. Tetapi anda boleh menggunakan jenis modul jsDoc dalam skrip taip dan anda juga boleh menggunakan jenis modul skrip taip dalam program javascript / js jsDoc juga. Jadi keputusan muktamad di tangan anda.

Ikut jalan bata kuning

Contoh kod VS menunjukkan betapa baiknya melihat Jenis anda dalam kod jsDoc, pada pendapat saya ini menghairankan bahawa lebih sedikit bunyi yang diberikan kepada kod anda.

Bonus

:: Coretan VS-Kod

/** @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';

:: kod jsdoc-duck

( dalam paparan ini sorotan sintaks tidak membantu untuk memahami Jenis ). Tetapi program pendek ini adalah contoh yang baik, jsDoc boleh menggunakan ciri lanjutan TS juga.

  "@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" },

selamat mengekod, menggali sebaliknya menambah kebergantungan

Atas ialah kandungan terperinci jsDoc Penginjilan. Untuk maklumat lanjut, sila ikut artikel berkaitan lain di laman web China PHP!