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.

+3


source to share


2 answers


Unfortunately, there is nothing quite like multiple tags.

like "@readonly, private" doesn't exist.



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

+4


source


In my opinion @readonly is better in this case. whether or not it is changed internally, it will only be read for an external user.



+3


source







All Articles