记录javascript方法的副作用

Question

我正在努力改进我的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!更好

Answer 1

从3.6.0版本开始，JSDoc有一个未正式记录的@modifies标签，正是为了这个目的。
参见commit 2f99af8和issue 1283。

---

上一个答案，包含用于添加自己的标记的参考。没有标准化的方法来做这件事。至少在JavaDoc中没有，公平地说，JSDoc正在模仿JavaDoc。顺便说一下，将它添加到JSDoc中有一个问题，它实际上引用了这个问题。

如果您真的想要对此进行记录，您可以添加一个自定义标记，就像您对JavaDoc所做的那样。您可以使用它来添加，例如，@affects标签。它的用法如下:

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

在JSDoc中定义自定义标记并不难，参见相关问题