@agds/jsdoc-plugin-ts

版本 ：1.0.4

jsdoc的ts支持插件（fork自better-docs）

快速开始

安装

npm i -D @agds/jsdoc-plugin-ts

效果展示

1. ts 的 type 类型声明

/**
 * ActionRequest
 * @memberof Action
 * @alias ActionRequest
 */
export type ActionRequest = {
    /**
     * parameters passed in an URL
     */
    params: {
        /**
         * Id of current resource
         */
        resourceId: string;
        /**
         * Id of current record
         */
        recordId?: string;
        /**
         * Name of an action
         */
        action: string;

        [key: string]: any;
    };
};

转换为:

/**
 * ActionRequest'
 *
 * @memberof Action'
 * @alias ActionRequest'
 * @typedef {object} ActionRequest'
 * @property {object} params   parameters passed in an URL'
 * @property {string} params.resourceId   Id of current resource'
 * @property {string} [params.recordId]   Id of current record'
 * @property {string} params.action   Name of an action'
 * @property {any} params.{...}'
 */

2. 您还可以用类似的方式对interface进行注释

/**
 * JSON representation of an {@link Action}
 * @see Action
 */
export default interface ActionJSON {
  /**
   * Unique action name
   */
  name: string;
  /**
   * Type of an action
   */
  actionType: 'record' | 'resource' | Array<'record' | 'resource'>;
  /**
   * Action icon
   */
  icon?: string;
  /**
   * Action label - visible on the frontend
   */
  label: string;
  /**
   * Guarding message
   */
  guard?: string;
  /**
   * If action should have a filter (for resource actions)
   */
  showFilter: boolean;
  /**
   * Action component. When set to false action will be invoked immediately after clicking it,
   * to put in another words: there wont be an action view
   */
  component?: string | false | null;
}

或者像那样描述你的class属性:

/**
 * Class name
 */
class ClassName {
  /**
   * Some private member which WONT be in jsdoc (because it is private)
   */
  private name: string

  /**
   * Some protected member which will go to the docs
   */
  protected somethingIsA: number

  /**
   * And static member which will goes to the docs.
   */
  static someStaticMember: number

  public notCommentedWontBeInJSDoc: string

  constructor(color: string) {}
}

如何使用

jsdoc 引入

请在根目录的jsdoc.conf.json的 plugins 字段新增插件的文件导入

{
  // 有时候需要指定node_modules,例如：`node_modules/@agds/jsdoc-plugin-ts`
  "plugins": [
+    "@agds/jsdoc-plugin-ts"
  ]
}

并在运行 jsdoc 时指定使用 config 文件

jsdoc -c jsdoc.conf.json

在@agds/cli-plugin-doc 中使用

请在根目录的agds.doc.config.js文件的导出对象的presets数组中新增对应的导入，可以无需设置直接使用

const tsPreset = require('@agds/jsdoc-plugin-ts/lib/agds-ts-preset');
module.exports =
/**
 * 配置参数
 *
 * @returns {import('@agds/cli-plugin-doc').RenderOptions}
 */
(async () => {
    return {
        presets:[
+          tsPreset
        ]
    };
})();

如果你要直接使用插件，请在根目录的agds.doc.config.js文件的导出对象的jsdocEngineOptions.plugins数组中新增对应的导入

const tsPreset = require('@agds/jsdoc-plugin-ts/lib/agds-ts-preset');
module.exports =
/**
 * 配置参数
 *
 * @returns {import('@agds/cli-plugin-doc').RenderOptions}
 */
(async () => {
    return {
      jsdocEngineOptions: {
        plugins:[
+        require.resolve('@agds/jsdoc-plugin-ts')
        ],
        source: {
           // jsdoc默认仅支持js、jsx文件，需要支持ts、tsx，需设置includePattern
+         includePattern: '\\.[jt]sx?$',
        }
      }
    };
})();

许可证

MIT License Copyright (c) 2021 锦阳

请维护者喝杯咖啡

加入钉钉群讨论或加入开发