On May 25, 2017, at 3:37 PM, Stuart Marks <stuart.ma...@oracle.com> wrote:
> The test in the @return paragraph is fine. I think you intended “text.” > The new text at the end of the @apiNote is ok... > > […] > > The "granularity" sentences currently in the @apiNote can remain, but > probably in a separate paragraph in the @apiNote. I agree with the foregoing. I’ll take another pass over it tomorrow. > The problem with fixing up javadoc in one place is that it becomes > inconsistent with other places. > > For example, File.length() has similar "Where it is required to > distinguish..." wording. This should also be made into an @apiNote and also > reworded to be in alignment with whatever text is used in File.lastModified(). > > Also, File.createNewFile(), File.delete(), and File.deleteOnExit() have words > to the effect of "Note: ..." or "Note that..." which indicate API notes, but > which aren't tagged with @apiNote. The @apiNote tag should probably be added > to those as well. > > These can be handled separately if you like. Unless you're really ambitious, > in which case you can fix them all in a single changeset. Up to you. I was only looking at this one particular thing and not reviewing the verbiage of the entire class. I would prefer to note the problems and file a separate issue to deal with them. Thanks, Brian
