18

我正在尝试改进我的 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!

4

1 回答 1

11

从 3.6.0 版本开始，JSDoc 有一个未记录的@modifies标签来实现这个目的。
请参阅提交 2f99af8和问题 1283。

上一个答案，包括添加您自己的标签的参考。没有标准化的方法来做到这一点。至少在 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 中定义自定义标签并不难，也请参阅这个相关问题。

于 2017-03-07T15:09:48.953 回答