Q:

Is there a way to state changes that will be applied to method parameters within Javadoc?

Imagine a method that applies changes to the parameterized objects. For example a map oder list passed.
If the developer decides not to create and return a copy of the parameter I guess it would be best to have a notice in the Javadoc of this method and the parameter which indicates these changes.
I could think of an alternate @param tag like @varparam or @refparam (Regarding pass-by-reference keywords of other programming languages).
The question is: Is there a common way to do those hints in Javadoc? How common is it to apply changes to parameters? I guess this could be a problem that appears often.

A:

There is no special tag that denotes this; the accepted practice is to clearly state that the method modifies the parameter object in the description section.
Although some don't like this style of code, there are some common methods in java core that do this. java.util.Arrays.sort (and a similar method in Collections) come to mind.

