Instead of writing it in the JavaDocs, it's much more appropriate to document this behavior in the User Guide

Gail Badner, you might want to backport this issue to 5.1 and 5.0.