COR-296 : Java API - Improve the javadoc