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.

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

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!