记录javascript方法的副作用

Question

我正在尝试改进我的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();
    }
};

这些是人为的例子和可能的"代码味道",但这是另一个问题.我正在研究如何记录这种行为(好的或坏的)的一些最佳实践.也许比这更好的东西//IMPORTANT!! This method is dangerous!

Answer 1

没有标准化的方法来做到这一点.至少在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中定义自定义标记并不难,也请参阅此相关问题.