Документирование побочных эффектов javascript-методов

Я пытаюсь улучшить документацию моего кода javascript и следую рекомендациям JSDoc https://jsdoc.app/.

Я не могу найти, как задокументировать намеренный побочный эффект. Например, следующий метод:

/**
  * @description
  *   Paints the object red.
  * @return
*/
Painter.paintItRed = function(someObj){
    someObj.color = "red";
};

Как вы документируете тот факт, что метод действует непосредственно на переданный объект? Другой пример:

/**
  * @description
  *   If the user has not setUp a config, show config Modal.
  * @return
*/
User.checkConfig = function(user){
    if(!user.config.valid){
       showConfigModal();
    }
};

Это надуманные примеры и вероятные "запахи кода", но это другая проблема. Я смотрю на некоторые лучшие практики о том, как документировать такое поведение (хорошо это или плохо). Что-то, возможно, лучше, чем //IMPORTANT!! This method is dangerous! //IMPORTANT!! This method is dangerous!

ОТВЕТЫ

Ответ 1

Нет стандартизированного способа сделать это. По крайней мере, не в JavaDoc, что, честно говоря, это то, что JSDoc имитирует. Кстати, есть проблема добавить его в JSDoc, который фактически ссылается на этот вопрос.

Если вы действительно хотите задокументировать это, вы можете добавить собственный тег, как вы можете для JavaDoc. Вы можете использовать это, например, для @affects тега @affects. Это можно использовать следующим образом.

/**
 * @description
 *   Paints the object red.
 * @param someObj
 *   The object to be painted.
 * @affects
 *   someObj.color
 */
Painter.paintItRed = function(someObj) {
    someObj.color = 'red';
};

Определить пользовательский тег в JSDoc несложно, также посмотрите этот связанный вопрос.