记录 javascript 方法的副作用答案

【问题标题】：documenting side-effects of javascript methods记录 javascript 方法的副作用
【发布时间】：2021-10-27 15:54:59
【问题描述】：

我正在尝试改进我的 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!更好的东西@

【问题讨论】：

我不知道，但我很喜欢！
我很久以前就问过这个问题，回头看我不确定它是否有价值。如果你的方法很短，名字很明显，并且在一个有意义的对象/命名空间中，那么它的作用就不应该有很多混乱。副作用的传统线索是方法接受参数但不返回任何内容。但是，如果语言总是返回最后一个表达式，则无法使用逻辑。所以你应该依赖一个能清楚显示动作的名字function doSomethingDangerous。

标签： javascript documentation jsdoc code-structure

【解决方案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。

【讨论】：