Add some javadoc

reader/src/main/java/org/jline/reader/Binding.java

@@ -8,5 +8,15 @@
  */
 package org.jline.reader;
 
+/**
+ * Marker interface for objects bound to key sequences.
+ *
+ * @see Macro
+ * @see Reference
+ * @see Widget
+ * @see org.jline.keymap.KeyMap
+ *
+ * @author <a href="mailto:gnodet@gmail.com">Guillaume Nodet</a>
+ */
 public interface Binding {
 }

reader/src/main/java/org/jline/reader/Candidate.java

@@ -10,6 +10,11 @@
 
 import java.util.Objects;
 
+/**
+ * A completion candidate.
+ *
+ * @author <a href="mailto:gnodet@gmail.com">Guillaume Nodet</a>
+ */
 public class Candidate implements Comparable<Candidate> {
 
     private final String value;
@@ -20,10 +25,18 @@ public class Candidate implements Comparable<Candidate> {
     private final String key;
     private final boolean complete;
 
+    /**
+     * Simple constructor with only a single String as an argument.
+     *
+     * @param value the candidate
+     */
     public Candidate(String value) {
         this(value, value, null, null, null, null, true);
     }
 
+    /**
+     * Constructs a new Candidate.
+     */
     public Candidate(String value, String displ, String group, String descr, String suffix, String key, boolean complete) {
         Objects.requireNonNull(value);
         this.value = value;
@@ -35,30 +48,73 @@ public Candidate(String value, String displ, String group, String descr, String
         this.complete = complete;
     }
 
+    /**
+     * The value that will be used for the actual completion.
+     * This string should not contain ANSI sequences.
+     */
     public String value() {
         return value;
     }
 
+    /**
+     * The string that will be displayed to the user.
+     * This string may contain ANSI sequences.
+     */
     public String displ() {
         return displ;
     }
 
+    /**
+     * The group name for this candidate.
+     * Candidates can be grouped together and this string is used
+     * as a key for the group and displayed to the user.
+     *
+     * @see LineReader.Option#GROUP
+     * @see LineReader.Option#AUTO_GROUP
+     */
     public String group() {
         return group;
     }
 
+    /**
+     * Description of this candidate, usually a small help message
+     * to understand the meaning of this candidate.
+     * This string may contain ANSI sequences.
+     */
     public String descr() {
         return descr;
     }
 
+    /**
+     * The suffix is added when this candidate is displayed.
+     * However, if the next character entered does not match,
+     * the suffix will be automatically removed.
+     * This string should not contain ANSI sequences.
+     *
+     * @see LineReader.Option#AUTO_REMOVE_SLASH
+     * @see LineReader#REMOVE_SUFFIX_CHARS
+     */
     public String suffix() {
         return suffix;
     }
 
+    /**
+     * Candidates which have the same key will be merged together.
+     * For example, if a command has multiple aliases, they can be merged
+     * if they are using the same key.
+     */
     public String key() {
         return key;
     }
 
+    /**
+     * Boolean indicating whether this candidate is complete or
+     * if the completer may further expand the candidate value
+     * after this candidate has been selected.
+     * This can be the case when completing folders for example.
+     * If the candidate is complete and is selected, a space
+     * separator will be added.
+     */
     public boolean complete() {
         return complete;
     }

reader/src/main/java/org/jline/reader/Completer.java

@@ -15,15 +15,20 @@
  *
  * @author <a href="mailto:mwp1@cornell.edu">Marc Prud'hommeaux</a>
  * @author <a href="mailto:jason@planet57.com">Jason Dillon</a>
+ * @author <a href="mailto:gnodet@gmail.com">Guillaume Nodet</a>
  * @since 2.3
  */
 public interface Completer
 {
     /**
      * Populates <i>candidates</i> with a list of possible completions for the <i>buffer</i>.
      *
-     * The <i>candidates</i> list will not be sorted before being displayed to the user: thus, the
-     * complete method should sort the {@link List} before returning.
+     * The list of candidates will be sorted and filtered by the LineReader, so that
+     * the list of candidates displayed to the user will usually be smaller than
+     * the list given by the completer.  Thus it is not necessary for the completer
+     * to do any matching based on the current buffer.  On the contrary, in order
+     * for the typo matcher to work, all possible candidates for the word being
+     * completed should be returned.
      *
      * @param line          The parsed command line
      * @param candidates    The {@link List} of candidates to populate

terminal/src/main/java/org/jline/utils/Display.java

@@ -11,7 +11,6 @@
 import java.io.IOError;
 import java.io.IOException;
 import java.io.StringWriter;
-import java.util.ArrayList;
 import java.util.Collections;
 import java.util.HashMap;
 import java.util.List;
@@ -58,7 +57,7 @@ public Display(Terminal terminal, boolean fullscreen) {
     }
 
     /** If cursor is at right margin, don't wrap immediately.
-     * See {@link LineReader.Option#DELAY_LINE_WRAP}.
+     * See {@link org.jline.reader.LineReader.Option#DELAY_LINE_WRAP}.
      */
     public boolean delayLineWrap() {
         return delayLineWrap;