javadoc improvements from LUCENE-763 by Steven Parkes; small javadoc parameter reordering to avoid warnings