Question

假设我有这样的工厂功能：

function Person(name, age) {
    return {name: name, age: age};
}

使用JSDoc3，我尝试以下列方式记录该功能：

/** Creates a Person object
 * @param {String} name The name of the person
 * @param {Number} age The person's age in years
 * @returns {object} The Person object specified */
function Person() {...}

显然，这会导致Person函数的文档生成为方法，并且不会提供有关返回对象结构的任何线索。

因此我尝试将其记录为类，如下所示：

/** Represents a person
 * @param {String} name The name of the person
 * @param {Number} age The person's age in years
 * @class*/
function Person(name, age) {
    return /** @lends Person.prototype */ {
        /** The name of the person */
        name: name, 
        /** The person's age in years */
        age: age
    };
}

不幸的是（除了文档注释不是DRY），将其记录为类将产生以下文本：

班级：人

人

new Person(name, age)   ...

请注意 new 关键字？

这不是我打算调用Person函数的方式，而是我在var joe = Person("Joe", 24);中使用它。

如何删除生成的文档中的new关键字？

更新

感谢下面评论中的所有想法/建议，以下是一些其他信息，以澄清一些事项：

我知道使用real classes (custom objects)可能会更好，做使用new来创建。然而，这个问题是关于使用JSDoc3 记录这些现有的工厂函数，从而产生有用的API参考。
我知道将function Person标记为@class在技术上是不正确的，因为它不用作类（不会new创建实例）。与使用@lends Person.prototype（感谢@nnnnnn指出这一点）在技术上不正确的方式相同，因为prototype的{{1}}不参与。同样，我为了文档目的而这样做，以便以可链接的方式记录人员实例的字段。
根据@Bálint和@nnnnnn的建议，我可以在Person的{{1}中记录Person的返回类型（即人物实例结构） }} 标签。这让我回到了我的第一次尝试，其中一个人实例文档只是一个文本描述，我不确定我是否可以从文档中的其他点链接到其成员：

如果Person被记录为@returns，我可以例如创建对人（及其字段）文档的引用，如下所示：

Person

如果我将@class的文档作为方法（作为上面的第一次尝试）并将有关人员对象结构的所有信息放在其/** Produces an array of {@link Person}s, sorted by their {@link Person#age}. * @param {Array} persons The persons to sort * @returns {Array} The sorted persons*/ function sortPersonsByAge(persons) { return persons.sort(function(a, b) {return a.age - b.age;}); }文档标记中，我该如何链接来自其他地方的类型及其字段/方法，如Person示例？

Answer 1

通过@typedef标记提供了技术上正确和生成漂亮文档的解决方案，该标记可用于与工厂函数分开记录返回类型。

在@typedef中，@property标记可用于定义字段：

/** Represents a person. Use the {@link Person} function to create one.
 * @typedef PersonObj
 * @property {String} name The name of the person
 * @property {Number} name The person's age in years */

然后，可以添加指向该类型的链接。工厂功能的文档：

/** Creates a {@link PersonObj}
 * @param {String} name The name of the person
 * @param {Number} age The person's age in years
 * @return {PersonObj} The new person object */
function Person(name, age) {
    return {
        name: name, 
        age: age
    };
}

希望其他人认为这有帮助。

Answer 2

由于我的previous answer根本没有导致@typedef成员@namespace，所以我使用了@memberof代码：

function

此模式的一个优点是类型的成员文档现在更接近它们在源中实际定义的位置。

一个缺点是成员在命名空间的文档中显示似乎需要num2words标记。

如何避免JavaScript工厂函数文档中的“新”（或更好地记录其返回类型）？

班级：人

人

更新

2 个答案: