BS-10051: update javadoc according to Chris