It is a good idea to put an example (or a pattern) into the method documentation. You can remove the inline example in this case. I suggest to do this for all methods. You can just copy the example into the main documentation (not the params); see http://stackoverflow.com/questions/541920/multiple-line-code-example-in-javadoc-comment