如何在 JSDoc 中注释“@readonly-but-modified-internally”成员/属性？答案

【问题标题】：How to annotate "@readonly-but-modified-internally" members / properties in JSDoc?如何在 JSDoc 中注释“@readonly-but-modified-internally”成员/属性？
【发布时间】：2015-01-05 00:33:41
【问题描述】：

JSDoc 有一个@readonly doclet tag:

@readonly 标签表明一个符号是只读的。

例如：

/**
* The name of the represented principal
* @member {string}
* @readonly
*/
this.name = primaryName;

但是，我真正想要传达和记录的是公共消费者应该将属性视为只读 - 但成员不是 em> 常数。

内部代码可以并且确实会修改此类成员：只读 doclet 标记用于 API 使用者。（如果 API 使用不当，他们会感到羞耻！- 但我不关心。）

/**
* Update the security token information.
* (This is a made-up example!)
*/
this.updateToken = function (token) { this.name = token.name; }

有没有什么好的方法可以在 JSDoc（标签）中表达这个概念？特别是，

有什么好办法表达“预计内部代码会修改这个只读成员”？

当然，在文档中除了 doclet 标记之外没有明确写出这样的内容。

我原本希望 JSDoc 能够轻松地接受“@readonly private”或类似的，但事实并非如此。使用自定义标签的问题在于，它是在本地引入的，在标准模板。

【问题讨论】：

标签： javascript documentation readonly jsdoc jsdoc3

【解决方案1】：

不幸的是，没有像多个标签一样的东西。

like “@readonly,private”不存在。

因此，您可以使用 @readonly 或 @private 中的任何一个，但您正在寻找的是目前不可能/不可用的东西（据我所知）。

【讨论】：

【解决方案2】：

在我看来 @readonly 在这种情况下是最好的。无论是内部修改，外部用户都是只读的。

【讨论】：