如何为QuickJS导出的无JSDoc原生类编写JSDoc注释？

由于QuickJS导出的原生类本身不携带类型信息，你需要在JavaScript代码中通过JSDoc补充类的属性、方法定义，让编辑器能识别类型并提供智能提示。以下是两种实用的实现方式：

方式一：在导入语句旁直接声明 #

在导入代码上方，用JSDoc的@class、@property、@method等标签直接描述原生类的结构：

/**
 * @module libSomeAwesomeCode.so
 */

/**
 * C++实现的原生核心类，提供XX功能
 * @class NativeClass
 * @property {string} instanceName - 实例名称，只读属性
 * @property {number} statusCode - 当前状态码，可读写
 */
/**
 * 执行核心业务操作
 * @method NativeClass#runTask
 * @param {string} taskId - 任务ID
 * @param {Object} config - 任务配置
 * @param {boolean} config.enableLog - 是否开启日志
 * @returns {Promise<{success: boolean, data: any}>} 返回异步操作结果
 */
/**
 * 创建实例的静态工厂方法
 * @method NativeClass.create
 * @param {number} initValue - 初始化参数
 * @returns {NativeClass} 返回新的类实例
 */
import {NativeClass} from "libSomeAwesomeCode.so";

这样编写后，编辑器就能识别NativeClass的类型、属性和方法，在使用时给出准确的代码提示。

方式二：单独创建统一声明文件 #

如果多个JS文件都需要导入这个原生类，可以创建一个单独的声明文件来统一维护类型信息，比如libSomeAwesomeCode.d.js：

/**
 * @module libSomeAwesomeCode.so
 */

/**
 * C++原生导出的核心类
 * @class NativeClass
 */
export class NativeClass {
    /**
     * 实例唯一标识
     * @type {string}
     * @readonly
     */
    uuid;

    /**
     * 当前运行计数
     * @type {number}
     */
    runCount;

    /**
     * 构造函数（仅当原生类支持通过new实例化时声明）
     * @param {string} initUuid - 初始化UUID
     */
    constructor(initUuid) {}

    /**
     * 重置实例状态
     * @param {boolean} clearData - 是否清空关联数据
     * @returns {void}
     */
    reset(clearData) {}

    /**
     * 静态初始化方法
     * @param {Object} options - 全局配置
     * @param {number} options.timeout - 超时时间（毫秒）
     * @returns {void}
     */
    static setup(options) {}
}

之后在需要导入的文件中，通过引用声明文件来关联类型：

/// <reference path="./libSomeAwesomeCode.d.js" />
import {NativeClass} from "libSomeAwesomeCode.so";

关键注意事项 #

• 若原生方法是异步的，用@returns {Promise<Type>}标注返回值类型
• 只读属性添加@readonly标签，避免编辑器提示可修改
• 如果原生类不支持new实例化（仅能通过静态方法创建），可省略constructor声明

内容的提问来源于stack exchange，提问作者Anurag Vohra