具有多个签名的文档构造函数答案

【问题标题】：Document constructor with multiple signatures具有多个签名的文档构造函数
【发布时间】：2013-08-15 11:04:37
【问题描述】：

我想知道如何使用 jsdoc 为构造函数定义两个签名：

makeClass("Person",
/** @lends Person */
{
    /**
        @constructs
        @param {int} p1
    */
    /**
        @constructs
        @param {string} p1
    */
    constructor: function () {

    },

    /**
        @name Person.prototype.func
        @function
        @param {object} arg arg desc
    */
    /**
        @name Person.prototype.func^2
        @function
        @param {int} arg arg desc
        @param {int} arg2 arg2 desc
    */
    func: function () {

    }
});

这会产生一个带有 {string} p1 的构造函数。

感谢您的帮助

【问题讨论】：

标签： javascript jsdoc

【解决方案1】：

JSDoc 没有可与 Visual Studio XML Doc 多重签名相媲美的概念。一种选择是将参数记录为具有多种可能的类型，并标记一些可选的。

/**
 * @param {Number|Object} arg Description of arg
 * @param {Number} [arg2] Description of arg2
 */

【讨论】：

【解决方案2】：

DocumentJS，JavascriptMVC 项目使用/创建的文档工具有released a new "@signature" annotation，允许您为同一方法注释多个签名。

我找不到太多documentation，但根据source（为简洁而编辑），它看起来很简单：

   /**
     * @signature `observe.attr()`
     * @return {Object<String, *>} an object with all the properties in this `can.Observe`.
     * 
     * @signature `observe.attr(key)`
     * @param {String} key the property to read
     * @return {*} the value assigned to _key_.
     *
     * @signature `observe.attr(key, value)`
     * @param {String} key the property to set
     * @param {*} the value to assign to _key_.
     * @return {can.Observe} this Observe, for chaining
     */
   attr: function( attr, val ) {

【讨论】：