A bunch more Javadoc fixes.

Wow, the 1.8 javadoc tool is much stricter. For the best I suppose, though requiring a <caption> for a <table> seems a bit excessive.
2014-06-25 13:14:46 -07:00
parent a9de4b243d
commit 8d6f9c216f
18 changed files with 77 additions and 82 deletions
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<project xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://maven.apache.org/POM/4.0.0">
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <parent>
    <groupId>org.sonatype.oss</groupId>
@@ -136,7 +136,7 @@ public class JDBCUtil
     * Issues a query with a potentially large number of keys in batches.  For example, you might
     * have 10,000 ids that you wish to use in an "in" clause, but don't trust the database to be
     * smart about optimizing that many keys, so instead you use batchQuery like so:
-     * <pre>
+     * <pre>{@code
     *    Collection<Integer> keys = ...;
     *    String query = "select NAME from USERS where USER_ID in (#KEYS)";
     *    JDBCUtil.BatchProcessor proc = new JDBCUtil.BatchProcessor() {
@@ -146,7 +146,7 @@ public class JDBCUtil
     *        }
     *    };
     *    JDBCUtil.batchQuery(conn, query, keys, false, 500, proc);
-     * </pre>
+     * }</pre>
     *
     * @param query the SQL query to run for each batch with the string <code>#KEYS#</code> in the
     * place where the batch of keys should be substituted.
@@ -99,7 +99,7 @@ public class Cursor<V>
     * clause: <CODE>record.table.Select("where name='xyz' for
     * update");</CODE><P>
     *
-     * <I><B>Attention!</I></B> Not all database drivers support update
+     * <I><B>Attention!</B></I> Not all database drivers support update
     * operation with cursor. This method will not work with such database
     * drivers.
     */
@@ -122,7 +122,7 @@ public class Cursor<V>
     * clause: <CODE>record.table.Select("where name='xyz' for
     * update");</CODE><P>
     *
-     * <I><B>Attention!</I></B> Not all database drivers support delete
+     * <I><B>Attention!</B></I> Not all database drivers support delete
     * operation with cursor.  This method will not work with such database
     * drivers.
     */
@@ -30,7 +30,7 @@ public class HttpPostUtil
     * <code>"Content-Type" = "application/x-www-form-urlencoded"</code>.
     *
     * @param url from which to make the request.
-     * @param submission the entire submission eg "foo=bar&baz=boo&futz=foo".
+     * @param submission the entire submission eg {@code foo=bar&baz=boo&futz=foo}.
     * @param timeout time to wait for the response, in seconds, or -1 for forever.
     */
    public static String httpPost (URL url, String submission, int timeout)
@@ -45,7 +45,7 @@ public class HttpPostUtil
     * thread, but this thread blocks until the results are returned or it times out.
     *
     * @param url from which to make the request.
-     * @param submission the entire submission eg "foo=bar&baz=boo&futz=foo".
+     * @param submission the entire submission eg {@code foo=bar&baz=boo&futz=foo}.
     * @param timeout time to wait for the response, in seconds, or -1 for forever.
     * @param requestProps additional request properties.
     */
@@ -17,8 +17,8 @@ import com.samskivert.util.StringUtil;
 public class HTMLUtil
 {
    /**
-     * Converts instances of <code><, >, & and "</code> into their
-     * entified equivalents: <code>&lt;, &gt;, &amp; and &quot;</code>.
+     * Converts instances of {@code<, >, & and "} into their
+     * entified equivalents: {@code&lt;, &gt;, &amp; and &quot;}.
     * These characters are mentioned in the HTML spec as being common
     * candidates for entification.
     *
@@ -43,7 +43,7 @@ public class HTMLUtil
    }

    /**
-     * Inserts a &lt;p&gt; tag between every two consecutive newlines.
+     * Inserts a @{code <p>} tag between every two consecutive newlines.
     */
    public static String makeParagraphs (String text)
    {
@@ -57,7 +57,7 @@ public class HTMLUtil
    }

    /**
-     * Inserts a &lt;br&gt; tag before every newline.
+     * Inserts a {@code <br>} tag before every newline.
     */
    public static String makeLinear (String text)
    {
@@ -27,7 +27,7 @@ import com.samskivert.util.Comparators;
 * have been translated via the internal mapping array. This way,
 * the TableSorter appears to hold another copy of the table
 * with the rows in a different order.
- * <p/>
+ * <p>
 * TableSorter registers itself as a listener to the underlying model,
 * just as the JTable itself would. Events recieved from the model
 * are examined, sometimes manipulated (typically widened), and then
@@ -35,7 +35,7 @@ import com.samskivert.util.Comparators;
 * If a change to the model has invalidated the order of TableSorter's
 * rows, a note of this is made and the sorter will resort the
 * rows the next time a value is requested.
- * <p/>
+ * <p>
 * When the tableHeader property is set, either by using the
 * setTableHeader() method or the two argument constructor, the
 * table header may be used as a complete UI for TableSorter.
@@ -58,7 +58,7 @@ import com.samskivert.util.Comparators;
 * that are already sorting - giving a way to initiate a compound
 * sort.
 * </ul>
- * <p/>
+ * <p>
 * This is a long overdue rewrite of a class of the same name that
 * first appeared in the swing table demos in 1997.
 *
@@ -69,7 +69,6 @@ import com.samskivert.util.Comparators;
 * @author Michael Bayne (modifications)
 * @version 2.0 02/27/04
 */
-
 public class TableSorter extends AbstractTableModel {
    protected TableModel tableModel;

@@ -18,7 +18,7 @@ import static com.samskivert.swing.Log.log;
 * application can safely manipulate its user interface in response to the
 * results of the task.
 *
- * <p/> Each task is run in it's own thread. Tasks are assumed to be
+ * <p> Each task is run in it's own thread. Tasks are assumed to be
 * infrequently run and expensive, so the overhead of creating a new
 * thread to run each task is considered acceptable. If the need arises,
 * the task master can be extended to support more sophisticated thread
@@ -430,7 +430,7 @@ public class ArrayUtil

    /**
     * Creates and returns a new array sized to fit and populated with the
-     * subset of values from indexes <code>0</code> to </code>offset -
+     * subset of values from indexes <code>0</code> to <code>offset -
     * 1</code> (inclusive) in the supplied array.
     *
     * @param values the array of values to splice.
@@ -447,7 +447,7 @@ public class ArrayUtil
    /**
     * Creates and returns a new array sized to fit and populated with the
     * concatenated subset of values from indexes <code>0</code> to
-     * </code>offset - 1</code>, and <code>offset + length</code> to
+     * <code>offset - 1</code>, and <code>offset + length</code> to
     * <code>values.length</code> (inclusive) in the supplied array.
     *
     * @param values the array of values to splice.
@@ -487,7 +487,7 @@ public class ArrayUtil

    /**
     * Creates and returns a new array sized to fit and populated with the
-     * subset of values from indexes <code>0</code> to </code>offset -
+     * subset of values from indexes <code>0</code> to <code>offset -
     * 1</code> (inclusive) in the supplied array.
     *
     * @param values the array of values to splice.
@@ -504,7 +504,7 @@ public class ArrayUtil
    /**
     * Creates and returns a new array sized to fit and populated with the
     * concatenated subset of values from indexes <code>0</code> to
-     * </code>offset - 1</code>, and <code>offset + length</code> to
+     * <code>offset - 1</code>, and <code>offset + length</code> to
     * <code>values.length</code> (inclusive) in the supplied array.
     *
     * @param values the array of values to splice.
@@ -544,7 +544,7 @@ public class ArrayUtil

    /**
     * Creates and returns a new array sized to fit and populated with the
-     * subset of values from indexes <code>0</code> to </code>offset -
+     * subset of values from indexes <code>0</code> to <code>offset -
     * 1</code> (inclusive) in the supplied array.
     *
     * @param values the array of values to splice.
@@ -561,7 +561,7 @@ public class ArrayUtil
    /**
     * Creates and returns a new array sized to fit and populated with the
     * concatenated subset of values from indexes <code>0</code> to
-     * </code>offset - 1</code>, and <code>offset + length</code> to
+     * <code>offset - 1</code>, and <code>offset + length</code> to
     * <code>values.length</code> (inclusive) in the supplied array.
     *
     * @param values the array of values to splice.
@@ -601,7 +601,7 @@ public class ArrayUtil

    /**
     * Creates and returns a new array sized to fit and populated with the
-     * subset of values from indexes <code>0</code> to </code>offset -
+     * subset of values from indexes <code>0</code> to <code>offset -
     * 1</code> (inclusive) in the supplied array.
     *
     * @param values the array of values to splice.
@@ -618,7 +618,7 @@ public class ArrayUtil
    /**
     * Creates and returns a new array sized to fit and populated with the
     * concatenated subset of values from indexes <code>0</code> to
-     * </code>offset - 1</code>, and <code>offset + length</code> to
+     * <code>offset - 1</code>, and <code>offset + length</code> to
     * <code>values.length</code> (inclusive) in the supplied array. The
     * type of the array is preserved.
     *
@@ -660,7 +660,7 @@ public class ArrayUtil

    /**
     * Creates and returns a new array sized to fit and populated with the
-     * subset of values from indexes <code>0</code> to </code>offset -
+     * subset of values from indexes <code>0</code> to <code>offset -
     * 1</code> (inclusive) in the supplied array.
     *
     * @param values the array of values to splice.
@@ -677,7 +677,7 @@ public class ArrayUtil
    /**
     * Creates and returns a new array sized to fit and populated with the
     * concatenated subset of values from indexes <code>0</code> to
-     * </code>offset - 1</code>, and <code>offset + length</code> to
+     * <code>offset - 1</code>, and <code>offset + length</code> to
     * <code>values.length</code> (inclusive) in the supplied array.
     *
     * @param values the array of values to splice.
@@ -16,9 +16,9 @@ import java.lang.reflect.Array;
 /**
 * Provides a base for extending the standard Java {@link ArrayList}
 * functionality (which we'd just extend directly if those pig fuckers hadn't
- * made the instance variables private).<p/>
+ * made the instance variables private).
 *
- * <em>Note:</em> Does not support null elements.
+ * <p><em>Note:</em> Does not support null elements.</p>
 */
 public abstract class BaseArrayList<E> extends AbstractList<E>
    implements RandomAccess, Cloneable, Serializable
@@ -11,12 +11,10 @@ import java.util.Comparator;
 import com.samskivert.annotation.ReplacedBy;

 /**
- * Provides a mechanism ({@link #sort}) for sorting the contents of the list
- * that doesn't involve creating two object arrays. Two copies of the elements
- * array are made if you called {@link java.util.Collections#sort}</code> (the
- * first is when {@link #toArray} is called on the collection and the second is
- * when {@link Arrays#sort} clones the supplied array so that it can do a merge
- * sort).
+ * Provides a mechanism ({@link #sort}) for sorting the contents of the list that doesn't involve
+ * creating two object arrays. Two copies of the elements array are made if you called {@link
+ * java.util.Collections#sort} (the first is when {@link #toArray} is called on the collection and
+ * the second is when {@link Arrays#sort} clones the supplied array so that it can do a merge sort).
 */
@ReplacedBy(
    value="java.util.ArrayList, java.util.TreeSet, or com.google.common.collect.TreeMultiset",
@@ -24,42 +24,35 @@ import static com.samskivert.util.UtilLog.log;
 * singleton class containing a config object that is configured to load its data from a single
 * configuration file. For example:
 *
- * <pre>
- * public class FooConfig
- * {
+ * <pre>{@code
+ * public class FooConfig {
 *     public static final String FIDDLES = "fiddles";
- *
 *     public static Config config = new Config("com/fribitz/foo");
 * }
- * </pre>
+ * }</pre>
 *
 * which would look for <code>com/fribitz/foo.properties</code> in the classpath and serve up those
 * configuration values when requests were made from <code>FooConfig.config</code>. For example:
 *
- * <pre>
+ * <pre>{@code
 *     int fiddles = FooConfig.config.getValue(FooConfig.FIDDLES, 0);
 *     for (int ii = 0; ii < fiddles; ii++) {
 *         fiddle();
 *     }
- * </pre>
+ * }</pre>
 *
 * An even better approach involves creating accessors for all defined configuration properties:
 *
- * <pre>
- * public class FooConfig
- * {
+ * <pre>{@code
+ * public class FooConfig {
 *     public static final String FIDDLES = "fiddles";
- *
 *     public static Config config = new Config("com/fribitz/foo");
- *
- *     public static int getFiddles ()
- *     {
+ *     public static int getFiddles () {
 *         return config.getValue(FIDDLES, FIDDLES_DEFAULT);
 *     }
- *
 *     protected static final int FIDDLES_DEFAULT = 0;
 * }
- * </pre>
+ * }</pre>
 *
 * This allows the default value for <code>fiddles</code> to be specified in one place and
 * simplifies life for the caller who can now simply request <code>FooConfig.getFiddles()</code>.
@@ -7,6 +7,7 @@ package com.samskivert.util;

 import java.math.BigInteger;
 import java.util.Iterator;
+import java.util.NoSuchElementException;

 /**
 * Various useful folds over iterables.
@@ -43,7 +43,7 @@ public class IntSets
    }

    /**
-     * Create a new IntSet, initially containing the ints in the specified Collection<Integer>.
+     * Create a new IntSet, initially containing the ints in the specified collection.
     */
    public static IntSet create (Collection<Integer> from)
    {
@@ -103,11 +103,11 @@ public final class Log
     * warning and error messages would be logged because info and debug
     * messages have a 'lower' log level.
     *
-     * <p/> Note: the log provider implementation may choose to propagate
+     * <p> Note: the log provider implementation may choose to propagate
     * the supplied level to all modules that are contained by this module
     * in the module hierarchy. For example, setting the "swing.util"
     * module to debug could also set the "swing.util.TaskMaster" level to
-     * debug because it is contained by the specified module.
+     * debug because it is contained by the specified module. </p>
     */
    public static void setLevel (String moduleName, int level)
    {
@@ -13,10 +13,8 @@ import java.util.NoSuchElementException;
 import com.samskivert.annotation.ReplacedBy;

 /**
- * Arbitrates membership.
- *
- * Example usage:
- * Find the best kind of peanut butter:
+ * Arbitrates membership. Example usage. Find the best kind of peanut butter:
+ * <pre>{@code
 * public Iterator<PeanutButter> findBestKinds (Collection<PeanutButter> pbs)
 * {
 *     return new Predicate<PeanutButter>() {
@@ -26,7 +24,7 @@ import com.samskivert.annotation.ReplacedBy;
 *         }
 *     }.filter(pbs.iterator());
 * }
- *
+ * }</pre>
 * An interface like this may someday be in the Java library, but until then...
 */
@ReplacedBy("com.google.common.base.Predicate")
@@ -164,10 +164,12 @@ public class RandomUtil
     * @return an index into the array, or -1 if the sum of the weights is less than 1.  For
     * example, passing in {1, 0, 3, 4} will return:
     *
-     * <table><tr><td>0</td><td>1/8th of the time</td></tr>
-     * <tr><td>1</td><td>never</td></tr>
-     * <tr><td>2</td><td>3/8th of the time</td></tr>
-     * <tr><td>3</td><td>half of the time</td></tr></table>
+     * <pre>{@code
+     * 0 - 1/8th of the time
+     * 1 - never
+     * 2 - 3/8th of the time
+     * 3 - half of the time
+     * }</pre>
     */
    public static int getWeightedIndex (int[] weights)
    {
@@ -184,10 +186,12 @@ public class RandomUtil
     * @return an index into the array, or -1 if the sum of the weights is less than 1.  For
     * example, passing in {1, 0, 3, 4} will return:
     *
-     * <table><tr><td>0</td><td>1/8th of the time</td></tr>
-     * <tr><td>1</td><td>never</td></tr>
-     * <tr><td>2</td><td>3/8th of the time</td></tr>
-     * <tr><td>3</td><td>half of the time</td></tr></table>
+     * <pre>{@code
+     * 0 - 1/8th of the time
+     * 1 - never
+     * 2 - 3/8th of the time
+     * 3 - half of the time
+     * }</pre>
     */
    public static int getWeightedIndex (int[] weights, Random r)
    {
@@ -216,10 +220,12 @@ public class RandomUtil
     * 0.0 or any individual element is negative.  For example, passing in {0.2, 0.0, 0.6, 0.8}
     * will return:
     *
-     * <table><tr><td>0</td><td>1/8th of the time</td></tr>
-     * <tr><td>1</td><td>never</td></tr>
-     * <tr><td>2</td><td>3/8th of the time</td></tr>
-     * <tr><td>3</td><td>half of the time</td></tr></table>
+     * <pre>{@code
+     * 0 - 1/8th of the time
+     * 1 - never
+     * 2 - 3/8th of the time
+     * 3 - half of the time
+     * }</pre>
     */
    public static int getWeightedIndex (float[] weights)
    {
@@ -236,10 +242,12 @@ public class RandomUtil
     * 0.0 or any individual element is negative.  For example, passing in {0.2, 0.0, 0.6, 0.8}
     * will return:
     *
-     * <table><tr><td>0</td><td>1/8th of the time</td></tr>
-     * <tr><td>1</td><td>never</td></tr>
-     * <tr><td>2</td><td>3/8th of the time</td></tr>
-     * <tr><td>3</td><td>half of the time</td></tr></table>
+     * <pre>{@code
+     * 0 - 1/8th of the time
+     * 1 - never
+     * 2 - 3/8th of the time
+     * 3 - half of the time
+     * }</pre>
     */
    public static int getWeightedIndex (float[] weights, Random r)
    {
@@ -17,7 +17,7 @@ package com.samskivert.util;
 * <p> The following contrived example will hopefully communicate its use
 * more clearly than the previous paragraph of flowery prose:
 *
- * <pre>
+ * <pre>{@code
 * public void doSomeStuff (ResultListener<String> listener)
 * {
 *     Runnable run = new Runnable () {
@@ -32,7 +32,7 @@ package com.samskivert.util;
 *     };
 *     new Thread(run).start();
 * }
- * </pre>
+ * }</pre>
 *
 * @see IntResultListener
 */
@@ -11,12 +11,10 @@ import java.util.Comparator;
 import com.samskivert.annotation.ReplacedBy;

 /**
- * Provides a mechanism ({@link #sort}) for sorting the contents of the list
- * that doesn't involve creating two object arrays. Two copies of the elements
- * array are made if you called {@link java.util.Collections#sort}</code> (the
- * first is when {@link #toArray} is called on the collection and the second is
- * when {@link Arrays#sort} clones the supplied array so that it can do a merge
- * sort).
+ * Provides a mechanism ({@link #sort}) for sorting the contents of the list that doesn't involve
+ * creating two object arrays. Two copies of the elements array are made if you called {@link
+ * java.util.Collections#sort} (the first is when {@link #toArray} is called on the collection and
+ * the second is when {@link Arrays#sort} clones the supplied array so that it can do a merge sort).
 */
@ReplacedBy(
    value="java.util.ArrayList, java.util.TreeSet, or com.google.common.collect.TreeMultiset",