3

JSDoc has a @readonly doclet tag:

The @readonly tag indicates that a symbol is intended to be read-only.

For example:

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

However, what I really want to communicate and document is that public consumers should treat the property as read-only - but the member is not constant.

Internal code can, and does, modify such members: the read-only doclet tag is for the API consumers. (And if the API is used incorrectly, shame on them! - but not my concern.)

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

Is there a good way to express this concept in JSDoc (tags)? In particular,

What is a good way to express "it is expected that internal code modifies this read-only member"?

Without writing such explicitly, aside from doclet tags, in the documentation of course.

I was originally hoping JSDoc would trivially accept "@readonly private" or similar, but such is not the case.. The issue with using a custom tag is that such is introduced locally, having no imminent external meaning or application in the standard templates.

user2864740
  • 60,010
  • 15
  • 145
  • 220

2 Answers2

4

Unfortunately there is nothing like multiple tags.

like “@readonly,private” is not there.

So you can use either of @readonly or @private but what you are looking for is something not possible/available currently (as per my knowledge).

H. Mahida
  • 2,356
  • 1
  • 12
  • 23
3

As per my opinion @readonly is best in this case. whether it modified internally, it will be read only for external user.

Laxmikant Dange
  • 7,606
  • 6
  • 40
  • 65