如何注释“@只读但内部修改”;JSDoc中的成员/属性

How to annotate "@readonly-but-modified-internally" members / properties in JSDoc?

本文关键字：JSDoc 修改 属性 成员 内部 何注释 注释 只读      更新时间：2023-09-26

JSDoc有一个@readonly doclet标记：

@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"或类似的内容，但事实并非如此。。使用自定义标记的问题是，它是在本地引入的，在标准模板中没有迫在眉睫的外部含义或应用程序。

不幸的是，没有什么比多个标签更好的了。

比如"@readonly，private"不存在

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

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

相关文章：