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

[Pavel Rappo]

On Thu, 23 Sep 2021 12:57:34 GMT, Alan Bateman <alanb at openjdk.org> wrote:

>> Please review this trivial change triggered by reading the java.nio.file documentation for an unrelated code review.
>
> 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;

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

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