jsDoc 布道

太长了；

使用遗留代码库 - 我们中的许多人无法一次又一次地躲避 - 让我尝试使用 jsdoc 而不是 typescript。我必须揭露令人惊讶的真相！

首先让我们清理一下： jsdoc 或 ts 只是意味着在开发人员时间下（包括稍后审查、重用、在任何环境中查看该代码：git 网页、随机编辑器、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 代码，此外两者之间存在虫洞。

最大的jsdoc功能恕我直言：这是使用标准的js注释系统，所以不要破坏任何js代码，这个代码将在js能够运行的任何地方运行。

jsdoc 编辑经验

我可以在任何编辑器中编写jsdoc，但很少有人理解它。

节点模块体验

我还创建了一个 npm 模块：jsdoc-duck：一个 jsdoc 编码模块。这强调了如果没有 typescript，就不可能创建 jsdoc npm 模块。也许如果我花更多的时间来弄清楚 vite 构建参数，那么就可以找到正确的解决方案。但好消息是，如果不在 npm 中使用该模块，而是借用我们的代码：只需将 index.js 复制到某个位置 - 那么我们就可以节省时间来向我们的程序插入新的依赖项，并且不会发生任何事情如果模块所有者将模块转为其他东西。

飞桨PaddlePaddle

飞桨PaddlePaddle开发者社区与布道，与社区共同进步

下载

jsdoc typescript 之间的虫洞

好消息是 typescript 和 jsdoc 相互兼容，只是 jsdoc 使用了一些不同的语法。但是您可以在打字稿中使用 jsdoc 模块类型，也可以在 javascript / js+jsdoc 程序中使用打字稿模块类型。所以最终决定权在你手中。

沿着黄砖路走

vs 代码示例展示了如何很好地看到 jsdoc 代码中的类型，在我看来，这给您的代码带来的噪音令人惊讶地减少了。

奖金

:: vs 代码片段

  "@type": {
    "prefix": ["ty"],
    "body": ["/** @type {$0} */"],
    "description": "jsdoc type"
  },

  "@typedef": {
    "prefix": ["td"],
    "body": ["/** @typedef {$1} foo */"],
    "description": "jsdoc typedef"
  },

:: jsdoc-duck 代码

（在此视图中语法突出显示无助于理解类型）。但是这个简短的程序是一个很好的例子，jsdoc 也可以使用 ts 的高级功能。

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

快乐编码，挖掘而不是添加依赖