--- a/src/jdk.internal.opt/share/classes/jdk/internal/joptsimple/OptionDeclarer.java	Wed Jun 06 13:06:21 2018 +0100
+++ b/src/jdk.internal.opt/share/classes/jdk/internal/joptsimple/OptionDeclarer.java	Wed Jun 06 15:36:29 2018 +0200
@@ -25,14 +25,20 @@
 
 package jdk.internal.joptsimple;
 
-import java.util.Collection;
+import java.util.List;
 
 /**
- * Trains the option parser. This interface aids integration with other code which may expose declaration of options but
- * not actual command-line parsing.
+ * Trains the option parser. This interface aids integration that disposes declaration of options but not actual
+ * command-line parsing.
+ *
+ * Typical use is for another class to implement {@code OptionDeclarer} as a facade, forwarding calls to an
+ * {@code OptionParser} instance.
+ *
+ * Note that although this is an interface, the returned values of calls are concrete jopt-simple classes.
  *
  * @author <a href="mailto:pholser@alumni.rice.edu">Paul Holser</a>
  * @see OptionParser
+ * @since 4.6
  */
 public interface OptionDeclarer {
     /**
@@ -78,12 +84,12 @@
      * @throws OptionException if any of the options contain illegal characters
      * @throws NullPointerException if the option list or any of its elements are {@code null}
      */
-    OptionSpecBuilder acceptsAll( Collection<String> options );
+    OptionSpecBuilder acceptsAll( List<String> options );
 
     /**
      * Tells the parser to recognize the given options, and treat them as synonymous.
      *
-     * @see #acceptsAll(Collection)
+     * @see #acceptsAll(List)
      * @param options the options to recognize and treat as synonymous
      * @param description a string that describes the purpose of the option.  This is used when generating help
      * information about the parser.
@@ -92,7 +98,7 @@
      * @throws NullPointerException if the option list or any of its elements are {@code null}
      * @throws IllegalArgumentException if the option list is empty
      */
-    OptionSpecBuilder acceptsAll( Collection<String> options, String description );
+    OptionSpecBuilder acceptsAll( List<String> options, String description );
 
     /**
      * Gives an object that represents an access point for non-option arguments on a command line.
@@ -127,7 +133,7 @@
     void allowsUnrecognizedOptions();
 
     /**
-     * Tells the parser either to recognize or ignore <kbd>"-W"</kbd>-style long options.
+     * Tells the parser either to recognize or ignore {@code -W}-style long options.
      *
      * @param recognize {@code true} if the parser is to recognize the special style of long options
      */