JSDoc Toolkit - 如何在同一行上指定@param和@property

Question

有没有办法避免必须为@property和@param键入两个单独的行,如果在示例中,在构造函数上,参数和属性具有相同的名称.

/**
 * Class for representing a point in 2D space.
 * @property {number} x The x coordinate of this point.
 * @property {number} y The y coordinate of this point.
 * @constructor
 * @param {number} x The x coordinate of this point.
 * @param {number} y The y coordinate of this point.
 * @return {Point} A new Point
 */
Point = function (x, y)
{
    this.x = x;
    this.y = y;
}

Answer 1

你不。这是不可能的，因为函数的参数和对象的属性 - 这些是不同的变量，它们不能同时是函数参数和对象属性。而且，这样的文档只会让开发者感到困惑，而无助于理解API。

我建议您不要在这篇文档中使用@properties，而是使用@type：

/**
 * Class for representing a point in 2D space.
 * @constructor
 * @param {number} x The x coordinate of this point.
 * @param {number} y The y coordinate of this point.
 * @return {Point} A new Point
 */
Point = function (x, y)
{
    /**
     * The x coordinate.
     * @type number
     */
    this.x = x;

    /**
     * The y coordinate.
     * @type number
     */
    this.y = y;
}

但实际上这么详细的文档是没有用的。我们在代码中谈论的内容Point.x = x对于任何小学生来说都是清楚的。