JavaScript 类具有返回 this 的 setter。我如何在 JsDoc 中记录这个？答案

【问题标题】：JavaScript class has setter that returns this. How do I document this in JsDoc?JavaScript 类具有返回 this 的 setter。我如何在 JsDoc 中记录这个？
【发布时间】：2014-03-05 03:21:24
【问题描述】：

示例代码：

var myObject = (function() {
    var M;

    M = function() {
    }

    M.prototype = {
        constructor: M,
        setSomeProperty = function(someValue) {
            // Do Stuff
            return this; // For chaining purposes
        }
    }

    return M
}());

在记录setSomeProperty 方法时，@returns 标记会是什么样子？

【问题讨论】：

标签： javascript jsdoc jsdoc3

【解决方案1】：

看起来像这样：

@returns {M} <code>this</code>

{M}表示返回的类别，<code>this</code>明确表示返回的内容。如果你使用markdown插件：

@returns {M} `this`

更详细的版本是：

@returns {M} The instance on which this method was called.

或者你可以省略类信息，让读者推断。

【讨论】：

我更喜欢最后一个版本。文档的想法是记录代码，而不是简单地逐字重复。
就在昨天，我遇到了一个库，其中有@returns <code>this</code> 本来可以立即理解并非常有用。仅仅阅读代码（这通常是在这些情况下给出的 pat 响应）并不清楚，因为顶级方法正在执行 return this.other_method(...)，它正在执行 return this.yet_another(...) 等。在文档中有 @returns <code>this</code>（无论如何我都在读）会立即说清楚。
就像在自动生成的文档中有意义的描述性文档注释一样，远离代码本身。