Improving Docs for both APIs, scala and java. Related to #3671