documenting side-effects of javascript methods

Question

I'm trying to improve the documentation of my javascript code, and am following the JSDoc guidelines https://jsdoc.app/.

I can't find how to document an intentional side-effect. For example the following method:

/**
  * @description
  *   Paints the object red.
  * @return
*/
Painter.paintItRed = function(someObj){
    someObj.color = "red";
};

How do you document the fact that the method acts directly on the passed object? A different example:

/**
  * @description
  *   If the user has not setUp a config, show config Modal.
  * @return
*/
User.checkConfig = function(user){
    if(!user.config.valid){
       showConfigModal();
    }
};

These are contrived examples and probable "code smells", but that's another issue. I'm looking at some best-practices on how to document such behavior (for good or bad). Something perhaps better than //IMPORTANT!! This method is dangerous!

I asked this question a long time ago and looking back at it I'm not sure it's that valuable. If your method is short, with an obvious name, and in a meaningful object/namespace there should not be a lot of confusion about what it's doing. A traditional clue for side-effects has been that a method takes an argument but does not return anything. However if the language always returns the last expression that logic can't be used. So you should rely on a name that clearly shows action `function doSomethingDangerous`. — mastaBlasta, Mar 07 '17 at 16:26

Just a student · Accepted Answer · 2021-10-27T07:54:59.947

Since version 3.6.0, JSDoc has an undocumented @modifies tag for exactly this purpose.
See commit 2f99af8 and issue 1283.

Previous answer, included for the reference to adding your own tag. There is no standardized way of doing this. At least not in JavaDoc, which, to be fair, is what JSDoc is mimicking. There is an issue to add it to JSDoc, by the way, that is actually referencing this question.

If you really want to document this, you can add a custom tag, like you can for JavaDoc. You could use that to add, for example, an @affects tag. It could be used as follows.

/**
 * @description
 *   Paints the object red.
 * @param someObj
 *   The object to be painted.
 * @affects
 *   someObj.color
 */
Painter.paintItRed = function(someObj) {
    someObj.color = 'red';
};

Defining a custom tag in JSDoc is not hard, also see this related question.

documenting side-effects of javascript methods

1 Answers1