JSDoc工具包 - 如何在同一行上指定@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;
}

- justtryingtomakealiving

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，任何学生都能理解。

- Microfed

---

我的建议是，你只需要像你现在这样从构造函数中声明jsdoc属性（即使它们稍后才会被赋值）。避免从类的随机函数中创建它们。 - Ruan Mendes