RFR: 8274195: Doc cleanup in java.nio.file

[Alan Bateman]

On Thu, 23 Sep 2021 13:11:27 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> src/java.base/share/classes/java/nio/file/FileVisitResult.java line 40:
>> 
>>> 38:      * Continue. If returned from the {@link FileVisitor#preVisitDirectory
>>> 39:      * preVisitDirectory} method then the entries in the directory are also
>>> 40:      * visited.
>> 
>> "When returned" -> "If returned" is okay.  
>> Returning CONTINUE is an indication to the caller that the entries should be visited, maybe leave it alone or else say "are also to be visited".
>
> Hm... One man's right is another man's responsibility. Can it be that implementors of FileVisitor are more central to this documentation than callers of FileVisitor? Is that case any different from the one below?
> 
>     /**
>      * Continue without visiting the <em>siblings</em> of this file or directory.
>      * If returned from the {@link FileVisitor#preVisitDirectory
>      * preVisitDirectory} method then the entries in the directory are also
>      * skipped and the {@link FileVisitor#postVisitDirectory postVisitDirectory}
>      * method is not invoked.
>      */
>     SKIP_SIBLINGS;

I would prefer to drop this change from your patch, otherwise we will be forced to make changes to several areas to keep things consistent.

-------------

PR: https://git.openjdk.java.net/jdk/pull/5649