How to comment out "@ readonly-but-modified-insideally" elements / properties in JSDoc?
JSDoc has @readonly
a doclet tag :
The @readonly tag indicates that the symbol is read-only.
For example:
/**
* The name of the represented principal
* @member {string}
* @readonly
*/
this.name = primaryName;
However, what I really want to link and document is that public consumers should treat the property as read-only, but the member is not persistent.
Internal code can and does modify these elements: the read-only doclet tag is for API users. (And if the API is misused, 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 "internal code is expected to modify this read-only member"?
Without writing this explicitly other than the doclet tags in the documentation, of course.
I originally hoped that JSDoc would trivially accept "@redonly private" or similar, but it doesn't. The problem with using a custom tag is that it is injected locally with no direct external value or attachment to the standard templates.
source to share