add JavaDoc for issue #506 and commit 1c001af