Alan, thanks for the comments. "returns true" works well for expressions containing exactly one method call, but e.g. in indexOf(String str, int fromIndex) it is a complex expression, where Sherman's "is true" would be more correct. Because of this, I'm still inclined not to change this.
http://cr.openjdk.java.net/~martin/webrevs/openjdk7/IndexOf-javadoc/ Martin On Mon, Apr 19, 2010 at 03:23, Alan Moore <uncle.al...@gmail.com> wrote: > On Thu, Apr 1, 2010 at 3:36 PM, Martin Buchholz <marti...@google.com> wrote: >> On Thu, Apr 1, 2010 at 14:35, Xueming Shen <xueming.s...@oracle.com> wrote: >>> Seems like the "is <code>true</code>." line is missing from the new wording >>> (in >>> all cases), is it purposely? Not a native, but I would assume we still need >>> those 2 words to make the sentence complete. >> >> It is true that "is true" >> would make it a grammatically complete sentence, >> but I think it's best to not be quite that pedantic and lawyerly. >> In general, the JDK makes a pretty good compromise between >> precision and readability. > I think Sherman has a good point, except the wording should be > "returns true" instead of "is true" (with, of course, "true" formatted > to indicate that it's a boolean literal, not an English word). That > would make it consistent with methods that return other-than-boolean > values, as well as being considerate of non-native English speakers > who see a method name like "startsWith" and _don't_ automatically read > it as the English phrase "starts with". >
