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 中所说的内容对任何小学生来说都是清楚的。