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

Question

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

例如：

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

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

内部代码可以并且确实修改了此类成员：只读 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”或类似的东西，但事实并非如此。使用自定义标签的问题是它是在本地引入的，在标准模板中没有直接的外部含义或应用程序。

score 4 · Accepted Answer

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

像“@readonly,private”不存在。

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

score 3 · Accepted Answer

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

2 回答 2