jsDoc エバンジェリズム

TLDR;

レガシー コード ベースで作業する - 私たちの多くは時間を追うごとに回避することができないため、私は Typescript の代わりに jsDoc を試すようになりました。驚くべき真実を明らかにしなければなりません!

まず最初にきれいにしましょう: jsDoc または TS は単に開発者時間中を意味します (後のレビュー、再利用、git Web ページ、ランダム エディター、Chrome、Firefox などのあらゆる環境でコードを確認することも含まれます)。 ..:devtool、vim、cat ... );

第一楽章

エディタを開いて適切なコメントを書いて、jsDoc が動作しているかどうかをテストしてください。

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

私の経験では、jsDoc は TS コードを置き換えることができますが、さらにこれら 2 つのコードの間にはワームホールが存在します。

jsDoc の最大の機能 私見: これは標準の JS コメント システムを使用しているため、JS コードを壊さないでください。このコードは、JS が実行できる場所であればどこでも実行されます。

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

jsDocエディターの経験

どのエディタでも jsDoc を書くことはできますが、それを理解できる人は稀です。

ノードモジュールのエクスペリエンス

npm モジュールも作成しました: jsdoc-duck: jsDoc コード化されたモジュール。これは、TypeScript がなければ jsDoc npm モジュールを作成できないことを強調しました。たぶん、もっと時間をかけて vite 構築パラメータを理解すれば、正しい解決策が見つかるかもしれません。しかし、良いニュースです。npm でそのモジュールを使用せず、代わりにコードを借用するのであれば、index.js を任意の場所にコピーするだけです。そうすれば、プログラムに新しい依存関係を挿入するために使用する必要がなくなり、何も起こらなくなります。モジュール所有者がモジュールを別のものに変更した場合。

jsDoc <-> 間のワームホールタイプスクリプト

嬉しいことに、Typescript と jsDoc は相互に互換性があります。jsDoc が使用する構文が少し異なるだけです。ただし、typescript で jsDoc モジュール タイプを使用することも、javascript / js jsDoc プログラムでも typescript モジュール タイプを使用することもできます。したがって、最終決定はあなたの手の中にあります。

黄色いレンガの道を進みます

VS コードの例は、jsDoc コード内の型をどのように適切に認識したかを示しています。私の意見では、これにより、コードに与えられるノイズが驚くほど少なくなります。

ボーナス

:: 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';

:: jsdoc-アヒルコード

(このビューでは、構文の強調表示はタイプを理解するのに役立ちません)。しかし、この短いプログラムは、jsDoc が 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" },

コーディングを楽しんでください。依存関係を追加する代わりに穴を掘ってください

以上がjsDoc エバンジェリズムの詳細内容です。詳細については、PHP 中国語 Web サイトの他の関連記事を参照してください。