Erroneous JavaDoc for Path#register

[Alan Bateman]

David M. Lloyd wrote:
> :
> Unfortunately, if you have a varargs method parameter which is of a 
> generic type, you'll generally get an annoying compile-time warning 
> stating that you're implicitly creating an array of generic type.  On 
> the other hand, the second parameter actually is an *explicit* generic 
> array creation, so...?
As Matthias said, we are using a wildcard type here so there shouldn't 
be a problem.

>
> Perhaps it would be better if both of these parameters were Set<> 
> types like this:
>
> public abstract WatchKey register(WatchService watcher,
>                                   Set<WatchEvent.Kind<?>> events,
>                                   Set<WatchEvent.Modifier> modifiers)
>                            throws IOException;
>
> This way, one could take advantage of EnumSet by creating enums to 
> implement each interface for a particular provider.  E.g. the standard 
> events class "StandardWatchEventKind" could become:
>
The java.nio.file package uses varargs a lot because it works nicely for 
the many cases where we don't need to specify any options/flags. The 
createFile/createDirectory/copyTo/moveTo/etc. methods are good examples 
of that. If we used a Set then we could use an EnumSet but we would need 
to pass in an empty set when there are no options or overload the method 
with a form that doesn't have any options.

For the register method it comes down to:
  key = dir.register(watcher, ENTRY_CREATE, ENTRY_DELETE);
-vs-
  key = dir.register(watcher, EnumSet.of(ENTRY_CREATE,ENTRY_DELETE));

Not a lot of difference except that watch events have a type parameter 
and so to use enum sets requires defining an enum per context type (as 
you found).  This, and because varargs are used extensively in this 
package,  I'm happy with the varargs form of this method.

-Alan.