javascript - 记录 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 更好!!这种方法很危险!

Answer 1

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

---

上一个答案，包括作为添加您自己的标签的引用。没有标准化的方法来执行此操作。至少not in JavaDoc ，公平地说，这是 JSDoc 正在模仿的。有 an issue顺便说一句，将其添加到 JSDoc 中，实际上是在引用这个问题。

如果你真的想记录这个，你可以添加一个自定义标签，就像你可以 for 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 中定义自定义标签 is not hard , 另见 this related question .