MAPREDUCE-3371. Review and improve the yarn-api javadocs. (Ravi Prakash via mahadev) - Merging r1206899 from trunk.