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» или подобное, но это не так. Проблема с использованием пользовательского тега заключается в том, что он вводится локально, не имея неизбежного внешнего значения или применения в стандартных шаблонах.
