记录JavaScript方法的副作用

内容来源于 Stack Overflow,并遵循CC BY-SA 3.0许可协议进行翻译与使用

  • 回答 (1)
  • 关注 (0)
  • 查看 (12)

我正在尝试改进我的JavaScript代码的文档,并遵循JSDoc准则http://usejsdoc.org/

我无法找到如何记录故意的副作用。例如以下方法:

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

这些是人为的例子和可能的“code smells”,但这是另一个问题。我正在研究如何记录这些行为(无论好坏)的最佳做法。或许比这更好//IMPORTANT!! This method is dangerous!

提问于
用户回答回答于

没有标准的做法。至少不是在JavaDoc中,公平的说就是JSDoc模仿的东西。顺便说一句,将它添加到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中定义一个自定义标签并不难,也可以看到这个相关的问题。

扫码关注云+社区