Document Side Effects with a block tag

[jdetle]

Problem:
In some cases when writing a function, side-effects are unavoidable, but they should be able to be documented.

Solution:
I'd be happy to try to go in and make a PR to include a side-effect tag for easy function documentation.

Proof that I'm not the only one concerned about this:
This StackOverflow question does a good job at summarizing my concern as well.

[typhonrt]

Welcome to ESDoc @jdetle! I'd wait to get a response from the ESDoc maintainer as he is opinionated on a lot of things before getting a PR going; it might be a long wait. It appears JSDoc also doesn't support such tags. If these tags were to be added following the Google closure compiler spec would be the way to go with @nosideeffect & @modifies.

[jdetle]

Oh man, what a great response! A @modifies tag would be great.

\cc @rgbkrk @captainsafia

[h13i32maru]

Sorry for late reply.

Your suggestion sounds good. I want to know detail of the tag.
For example, does the following specification satisfy your desire?

export default class Foo {
  /**
   * @param {number[]} arr
   * @sideeffect {this} when call this method, modifies this. (case 1)
   * @sideeffect {this.p} when call this method, modifies this.p (case 2)
   * @sideeffect {arguments} when call this method, modifies arguments (case 3)
   * @sideeffect {arguments.arr} when call this method, modifies arguments arr (case 4)
   * @sideeffect {AwesomeSingleton} then call this method, modifies instance of AwesomeSingleton (case 5)
   */
  bar(arr) {
    this.p++;
    arr[0]++;
    AwesomeSingleton.p++;
  }
}

HoweverI have uneasy about {this} and {arguments} because the words are new for ESDoc. If you have a better syntax, please tell me.

[jdetle]

I think @modifies works, best to use the current practice than introduce something new. I think this and arguments have a specific meaning in Javascript that is getting used here correctly so there shouldn't be any issue with using them in documentation.

[alexalv]

Any news on this issue?