JavaScript库同名函数文档识别错误问题求助

问题原因 #

这种情况是代码结构+文档工具识别逻辑共同导致的：

• 当前将User和Controls作为MyLibrary的属性，值为构造函数，内部通过this挂载实例方法；
• 多数文档工具（如JSDoc）默认会对全局/命名空间下的同名函数做合并处理，如果没有明确的类归属标识，工具无法区分不同构造函数实例上的同名方法，只会优先识别第一个出现的函数签名。

解决建议 #

1. 用JSDoc标签明确类与方法的归属 #

给构造函数添加@class标识，给内部方法添加@memberof和@instance标签，让文档工具清晰识别方法所属的类：

/**
 * 我的库命名空间
 * @namespace MyLibrary
 */
var MyLibrary = MyLibrary || {};

/**
 * 用户类
 * @class MyLibrary.User
 * @param {*} T - 构造函数参数
 */
MyLibrary.User = function (T) {
    /**
     * User类的实例方法function1
     * @memberof MyLibrary.User
     * @instance
     */
    this.function1 = function () {
        return "1";
    };

    /**
     * User类的实例方法function2
     * @memberof MyLibrary.User
     * @instance
     * @returns {string} 返回值说明
     */
    this.function2 = function () {
        return "2";
    };
};

/**
 * 控件类
 * @class MyLibrary.Controls
 * @param {*} T - 构造函数参数
 */
MyLibrary.Controls = function (T) {
    /**
     * Controls类的实例方法function1
     * @memberof MyLibrary.Controls
     * @instance
     */
    this.function1 = function () {
        return "1";
    };

    /**
     * Controls类的实例方法function2
     * @memberof MyLibrary.Controls
     * @instance
     * @returns {string} 返回值说明
     */
    this.function2 = function () {
        return "2";
    };
};

2. 改用原型链挂载方法 #

将方法挂载到构造函数的原型上，这种结构更符合JavaScript类的规范，文档工具对原型方法的识别准确性更高：

/**
 * 我的库命名空间
 * @namespace MyLibrary
 */
var MyLibrary = MyLibrary || {};

/**
 * 用户类
 * @class MyLibrary.User
 * @param {*} T - 构造函数参数
 */
MyLibrary.User = function (T) {
    // 构造函数初始化逻辑
};

/**
 * User类的实例方法function1
 * @memberof MyLibrary.User
 * @instance
 * @returns {string} 返回值说明
 */
MyLibrary.User.prototype.function1 = function () {
    return "1";
};

/**
 * User类的实例方法function2
 * @memberof MyLibrary.User
 * @instance
 * @returns {string} 返回值说明
 */
MyLibrary.User.prototype.function2 = function () {
    return "2";
};

/**
 * 控件类
 * @class MyLibrary.Controls
 * @param {*} T - 构造函数参数
 */
MyLibrary.Controls = function (T) {
    // 构造函数初始化逻辑
};

/**
 * Controls类的实例方法function1
 * @memberof MyLibrary.Controls
 * @instance
 * @returns {string} 返回值说明
 */
MyLibrary.Controls.prototype.function1 = function () {
    return "1";
};

/**
 * Controls类的实例方法function2
 * @memberof MyLibrary.Controls
 * @instance
 * @returns {string} 返回值说明
 */
MyLibrary.Controls.prototype.function2 = function () {
    return "2";
};

3. 检查文档工具配置 #

以JSDoc为例，确保配置文件（如jsdoc.json）满足以下要求：

• 启用@class、@memberof、@instance等必要标签；
• source.include字段正确包含你的代码文件，无遗漏或错误排除；
• 若需自定义命名空间解析规则，可在配置中添加对应设置。

4. 给实例方法添加具名函数 #

将构造函数内的匿名函数改为具名函数，帮助文档工具区分不同类的同名方法：

this.function1 = function User_function1() {
    return "1";
};

内容的提问来源于stack exchange，提问作者Oliver Rodrigues