COR-295 : Java API - Improve the javadoc