如何为带有多个别名的JavaScript方法编写文档？

嘿，针对你这个Person构造函数里方法有别名的JSDoc文档问题，我有两个实用的方案分享给你～

方案一：在主方法的JSDoc里用@alias标注别名 #

这是最简洁且易维护的方式，直接在核心方法getName()的文档中添加@alias标签，把所有别名都关联起来。主流的JSDoc工具都能识别这个标签，生成文档时会自动把三个方法指向同一份说明。修改后的代码如下：

/**
 * Creates a person instance.
 * @param {string} name The person's full name.
 * @constructor
 */
function Person( name ) {
    /**
     * Returns the person's full name.
     * @return {string} The current person's full name.
     * @alias Person.getN
     * @alias Person.getFullName
     */
    function getName() {
        return name;
    }
    this.getName = getName;
    this.getN = getName;
    this.getFullName = getName;
}

这样做的好处是，后续如果要修改方法的说明，只需要更新getName()的文档就好，不用逐个修改别名的文档，减少维护成本。

方案二：为每个别名添加简短文档并链接到主方法 #

如果你希望每个别名的文档里能直接显示关联提示，可以给每个别名单独加简短的JSDoc，用@link标签指向主方法。代码示例如下：

/**
 * Creates a person instance.
 * @param {string} name The person's full name.
 * @constructor
 */
function Person( name ) {
    /**
     * Returns the person's full name.
     * @return {string} The current person's full name.
     */
    function getName() {
        return name;
    }
    this.getName = getName;
    /**
     * Alias for {@link Person.getName}
     * @function
     * @returns {string} The current person's full name.
     */
    this.getN = getName;
    /**
     * Alias for {@link Person.getName}
     * @function
     * @returns {string} The current person's full name.
     */
    this.getFullName = getName;
}

这种方式更直观，用户查看任何一个别名的文档时，都能立刻知道它是getName()的替代方法，不过需要注意保持返回值等信息和主方法一致。

总体来说，方案一更推荐，兼顾简洁性和可维护性～

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