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();
    }
};

这些是人为的例子和可能的代码气味＆＃34;但这是另一个问题。我正在研究如何记录这种行为的一些最佳实践（好的或坏的）。可能比//IMPORTANT!! This method is dangerous!

更好的东西

Answer 1

没有标准化的方法。至少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。

记录javascript方法的副作用

1 个答案: