refinements to annotations and javadocs