Remove javadoc warnings

.gitignore

@@ -5,3 +5,4 @@ target
 .settings/
 .idea
 build.rc
+.vscode

builtins/src/main/java/org/jline/builtins/Completers.java

@@ -257,11 +257,10 @@ protected Path getUserDir() {
     /**
      * A file name completer takes the buffer and issues a list of
      * potential completions.
-     * <p/>
+     * <p>
      * This completer tries to behave as similar as possible to
      * <i>bash</i>'s file name completion (using GNU readline)
      * with the following exceptions:
-     * <p/>
      * <ul>
      * <li>Candidates that are directories will end with "/"</li>
      * <li>Wildcard regular expressions are not evaluated or replaced</li>

builtins/src/main/java/org/jline/builtins/Less.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2002-2017, the original author or authors.
+ * Copyright (c) 2002-2018, the original author or authors.
  *
  * This software is distributable under the BSD license. See the terms of the
  * BSD license in the documentation provided with this software.
@@ -646,7 +646,7 @@ AttributedString getLine(int line) throws IOException {
     /**
      * This is for long running commands to be interrupted by ctrl-c
      *
-     * @throws InterruptedException
+     * @throws InterruptedException if the thread has been interruped
      */
     public static void checkInterrupted() throws InterruptedException {
         Thread.yield();

builtins/src/main/java/org/jline/builtins/NfaMatcher.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2002-2017, the original author or authors.
+ * Copyright (c) 2002-2018, the original author or authors.
  *
  * This software is distributable under the BSD license. See the terms of the
  * BSD license in the documentation provided with this software.
@@ -52,6 +52,9 @@ public boolean match(List<T> args) {
 
     /**
      * Returns the list of possible matcher names for the next object
+     *
+     * @param args input list
+     * @return the list of possible matcher names for the next object
      */
     public Set<String> matchPartial(List<T> args) {
         Set<State> clist = new HashSet<>();

builtins/src/main/java/org/jline/builtins/Options.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2002-2016, the original author or authors.
+ * Copyright (c) 2002-2018, the original author or authors.
  *
  * This software is distributable under the BSD license. See the terms of the
  * BSD license in the documentation provided with this software.
@@ -241,7 +241,10 @@ public void usage(PrintStream err) {
     }
 
     /**
-     * prints usage message and returns IllegalArgumentException, for you to throw.
+     * Prints usage message and returns IllegalArgumentException, for you to throw.
+     *
+     * @param s the message to display
+     * @return an exception with the generated message
      */
     public IllegalArgumentException usageError(String s) {
         error = usageName + ": " + s;

reader/src/main/java/org/jline/keymap/BindingReader.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2002-2016, the original author or authors.
+ * Copyright (c) 2002-2018, the original author or authors.
  *
  * This software is distributable under the BSD license. See the terms of the
  * BSD license in the documentation provided with this software.
@@ -49,6 +49,7 @@ public BindingReader(NonBlockingReader reader) {
      * will be returned.
      *
      * @param keys the KeyMap to use for decoding the input stream
+     * @param <T> the type of bindings to be read
      * @return the decoded binding or <code>null</code> if the end of
      *         stream has been reached
      */

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2002-2016, the original author or authors.
+ * Copyright (c) 2002-2018, the original author or authors.
  *
  * This software is distributable under the BSD license. See the terms of the
  * BSD license in the documentation provided with this software.
@@ -36,6 +36,14 @@ public Candidate(String value) {
 
     /**
      * Constructs a new Candidate.
+     *
+     * @param value the value
+     * @param displ the display string
+     * @param group the group
+     * @param descr the description
+     * @param suffix the suffix
+     * @param key the key
+     * @param complete the complete flag
      */
     public Candidate(String value, String displ, String group, String descr, String suffix, String key, boolean complete) {
         Objects.requireNonNull(value);
@@ -51,6 +59,7 @@ public Candidate(String value, String displ, String group, String descr, String
     /**
      * The value that will be used for the actual completion.
      * This string should not contain ANSI sequences.
+     * @return the value
      */
     public String value() {
         return value;
@@ -59,6 +68,7 @@ public String value() {
     /**
      * The string that will be displayed to the user.
      * This string may contain ANSI sequences.
+     * @return the display string
      */
     public String displ() {
         return displ;
@@ -68,6 +78,7 @@ public String 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.
+     * @return the group
      *
      * @see LineReader.Option#GROUP
      * @see LineReader.Option#AUTO_GROUP
@@ -80,6 +91,7 @@ public String group() {
      * Description of this candidate, usually a small help message
      * to understand the meaning of this candidate.
      * This string may contain ANSI sequences.
+     * @return the description
      */
     public String descr() {
         return descr;
@@ -90,6 +102,7 @@ public String descr() {
      * However, if the next character entered does not match,
      * the suffix will be automatically removed.
      * This string should not contain ANSI sequences.
+     * @return the suffix
      *
      * @see LineReader.Option#AUTO_REMOVE_SLASH
      * @see LineReader#REMOVE_SUFFIX_CHARS
@@ -102,6 +115,7 @@ public String 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.
+     * @return the key
      */
     public String key() {
         return key;
@@ -114,6 +128,7 @@ public String key() {
      * This can be the case when completing folders for example.
      * If the candidate is complete and is selected, a space
      * separator will be added.
+     * @return the completion flag
      */
     public boolean complete() {
         return complete;

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2002-2016, the original author or authors.
+ * Copyright (c) 2002-2018, the original author or authors.
  *
  * This software is distributable under the BSD license. See the terms of the
  * BSD license in the documentation provided with this software.
@@ -30,6 +30,7 @@ public interface Completer
      * for the typo matcher to work, all possible candidates for the word being
      * completed should be returned.
      *
+     * @param reader        The line reader
      * @param line          The parsed command line
      * @param candidates    The {@link List} of candidates to populate
      */

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2002-2016, the original author or authors.
+ * Copyright (c) 2002-2018, the original author or authors.
  *
  * This software is distributable under the BSD license. See the terms of the
  * BSD license in the documentation provided with this software.
@@ -25,21 +25,25 @@ public interface History extends Iterable<History.Entry>
 
     /**
      * Initialize the history for the given reader.
+     * @param reader the reader to attach to
      */
     void attach(LineReader reader);
 
     /**
      * Load history.
+     * @throws IOException if a problem occurs
      */
     void load() throws IOException;
 
     /**
      * Save history.
+     * @throws IOException if a problem occurs
      */
     void save() throws IOException;
 
     /**
      * Purge history.
+     * @throws IOException if a problem occurs
      */
     void purge() throws IOException;
 
@@ -107,6 +111,8 @@ public Entry next() {
 
     /**
      * Return the content of the current buffer.
+     *
+     * @return the content of the current buffer
      */
     String current();
 
@@ -143,6 +149,9 @@ public Entry next() {
 
     /**
      * Move to the specified index in the history
+     *
+     * @param index The index to move to.
+     * @return      Returns true if the index was moved.
      */
     boolean moveTo(int index);
 

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

@@ -19,7 +19,6 @@
 /** Read lines from the console, with input editing.
  *
  * <h3>Prompt strings</h3>
- * <p>
  * It is traditional for an interactive console-based program
  * to print a short prompt string to signal that the user is expected
  * to type a command.  JLine supports 3 kinds of prompt string:
@@ -33,13 +32,14 @@
  * All of these are specified with prompt templates,
  * which are similar to {@code printf} format strings,
  * using the character {@code '%'} to indicate special functionality.
- * <p>
+ * </p>
  * The pattern may include ANSI escapes.
  * It may include these template markers:
  * <dl>
  * <dt>{@code %N}</dt>
  * <dd>A line number. This is the sum of {@code getLineNumber()}
  *   and a counter starting with 1 for the first continuation line.
+ * </dd>
  * <dt>{@code %M}</dt>
  * <dd>A short word explaining what is "missing". This is supplied from
  * the {@link EOFError#getMissing()} method, if provided.
@@ -56,17 +56,15 @@
  * <dt>{@code %%}</dt>
  * <dd>A literal {@code '%'}.
  * </dd>
- * <dt><code>%{</code></dt>
- * <dt><code>%}</code></dt>
- * Text between a <code>%{</code>...<code>%}</code> pair is printed as
+ * <dt><code>%{</code></dt><dt><code>%}</code></dt>
+ * <dd>Text between a <code>%{</code>...<code>%}</code> pair is printed as
  * part of a prompt, but not interpreted by JLine
  * (except that {@code '%'}-escapes are processed).  The text is assumed
  * to take zero columns (not move the cursor).  If it changes the style,
  * you're responsible for changing it back.  Standard ANSI escape sequences
  * do not need to be within a <code>%{</code>...<code>%}</code> pair
  * (though can be) since JLine knows how to deal with them.  However,
  * these delimiters are needed for unusual non-standard escape sequences.
- * <dd>
  * </dd>
  * </dl>
  */
@@ -379,7 +377,7 @@ enum Option {
         DELAY_LINE_WRAP,
         AUTO_PARAM_SLASH(true),
         AUTO_REMOVE_SLASH(true),
-        /** When hitting the <tab> key at the beginning of the line, insert a tabulation
+        /** When hitting the <code>&lt;tab&gt;</code> key at the beginning of the line, insert a tabulation
          *  instead of completing.  This is mainly useful when {@link #BRACKETED_PASTE} is
          *  disabled, so that copy/paste of indented text does not trigger completion.
          */
@@ -423,7 +421,11 @@ enum RegionType {
     /**
      * Read the next line and return the contents of the buffer.
      *
-     * Equivalent to <code>readLine(null, null, null)</code>
+     * Equivalent to <code>readLine(null, null, null)</code>.
+     *
+     * @return the line read
+     * @throws UserInterruptException If the call was interrupted by the user.
+     * @throws EndOfFileException     If the end of the input stream was reached.
      */
     String readLine() throws UserInterruptException, EndOfFileException;
 
@@ -432,6 +434,11 @@ enum RegionType {
      * characters will be echoed. If 0, then no characters will be echoed.
      *
      * Equivalent to <code>readLine(null, mask, null)</code>
+     *
+     * @param mask      The mask character, <code>null</code> or <code>0</code>.
+     * @return          A line that is read from the terminal, can never be null.
+     * @throws UserInterruptException If the call was interrupted by the user.
+     * @throws EndOfFileException     If the end of the input stream was reached.
      */
     String readLine(Character mask) throws UserInterruptException, EndOfFileException;
 
@@ -440,6 +447,11 @@ enum RegionType {
      * If null, then the default prompt will be used.
      *
      * Equivalent to <code>readLine(prompt, null, null)</code>
+     *
+     * @param prompt    The prompt to issue to the terminal, may be null.
+     * @return          A line that is read from the terminal, can never be null.
+     * @throws UserInterruptException If the call was interrupted by the user.
+     * @throws EndOfFileException     If the end of the input stream was reached.
      */
     String readLine(String prompt) throws UserInterruptException, EndOfFileException;
 
@@ -448,21 +460,29 @@ enum RegionType {
      * (without any trailing newlines).
      *
      * Equivalent to <code>readLine(prompt, mask, null)</code>
+     *
+     * @param prompt    The prompt to issue to the terminal, may be null.
+     * @param mask      The mask character, <code>null</code> or <code>0</code>.
+     * @return          A line that is read from the terminal, can never be null.
+     * @throws UserInterruptException If the call was interrupted by the user.
+     * @throws EndOfFileException     If the end of the input stream was reached.
      */
     String readLine(String prompt, Character mask) throws UserInterruptException, EndOfFileException;
 
     /**
      * Read a line from the <i>in</i> {@link InputStream}, and return the line
      * (without any trailing newlines).
      *
+     * Equivalent to <code>readLine(prompt, null, mask, buffer)</code>
+     *
      * @param prompt    The prompt to issue to the terminal, may be null.
      *   This is a template, with optional {@code '%'} escapes, as
      *   described in the class header.
      * @param mask      The character mask, may be null.
      * @param buffer    The default value presented to the user to edit, may be null.
      * @return          A line that is read from the terminal, can never be null.
-     *
-     * Equivalent to <code>readLine(prompt, null, mask, buffer)</code>
+     * @throws UserInterruptException If the call was interrupted by the user.
+     * @throws EndOfFileException     If the end of the input stream was reached.
      */
     String readLine(String prompt, Character mask, String buffer) throws UserInterruptException, EndOfFileException;
 
@@ -483,6 +503,8 @@ enum RegionType {
      * @throws UserInterruptException if readLine was interrupted (using Ctrl-C for example)
      * @throws EndOfFileException if an EOF has been found (using Ctrl-D for example)
      * @throws java.io.IOError in case of other i/o errors
+     * @throws UserInterruptException If the call was interrupted by the user.
+     * @throws EndOfFileException     If the end of the input stream was reached.
      */
     String readLine(String prompt, String rightPrompt, Character mask, String buffer) throws UserInterruptException, EndOfFileException;
 
@@ -503,6 +525,8 @@ enum RegionType {
      * @throws UserInterruptException if readLine was interrupted (using Ctrl-C for example)
      * @throws EndOfFileException if an EOF has been found (using Ctrl-D for example)
      * @throws java.io.IOError in case of other i/o errors
+     * @throws UserInterruptException If the call was interrupted by the user.
+     * @throws EndOfFileException     If the end of the input stream was reached.
      */
     String readLine(String prompt, String rightPrompt, MaskingCallback maskingCallback, String buffer) throws UserInterruptException, EndOfFileException;
 

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2002-2017, the original author or authors.
+ * Copyright (c) 2002-2018, the original author or authors.
  *
  * This software is distributable under the BSD license. See the terms of the
  * BSD license in the documentation provided with this software.
@@ -16,11 +16,19 @@ public interface MaskingCallback {
     /**
      * Transforms the line before it is displayed so that
      * some parts can be hidden.
+     *
+     * @param line the current line being edited
+     * @return the modified line to display
      */
     String display(String line);
 
     /**
      * Transforms the line before storing in the history.
+     * If the return value is empty or null, it will not be saved
+     * in the history.
+     *
+     * @param line the line to be added to history
+     * @return the modified line
      */
     String history(String line);