Fix all Javadoc warnings

"mvn javadoc:javadoc" should now report 0 warnings.
See ome#2

src/main/java/loci/common/AbstractNIOHandle.java

@@ -40,7 +40,7 @@
  * @see IRandomAccess
  * @see java.io.RandomAccessFile
  *
- * @author Chris Allan <callan at blackcat dot ca>
+ * @author Chris Allan (callan at blackcat dot ca)
  */
 public abstract class AbstractNIOHandle implements IRandomAccess {
 

src/main/java/loci/common/BZip2Handle.java

@@ -52,6 +52,7 @@ public class BZip2Handle extends StreamHandle {
   /**
    * Construct a new BZip2Handle corresponding to the given file.
    *
+   * @param file the path to a file on disk
    * @throws HandleException if the given file is not a BZip2 file.
    */
   public BZip2Handle(String file) throws IOException {
@@ -77,7 +78,14 @@ public BZip2Handle(String file) throws IOException {
 
   // -- BZip2Handle API methods --
 
-  /** Returns true if the given filename is a BZip2 file. */
+  /**
+   * Returns true if the given filename is a BZip2 file.
+   *
+   * @param file the path to a file on disk
+   * @return true if file's extension is .bz2 and the
+   *         first 2 bytes are the BZip2 magic marker
+   * @throws IOException if the file is not readable
+   */
   public static boolean isBZip2File(String file) throws IOException {
     if (!file.toLowerCase().endsWith(".bz2")) {
       return false;

src/main/java/loci/common/ByteArrayHandle.java

@@ -60,11 +60,20 @@ public class ByteArrayHandle extends AbstractNIOHandle {
   /**
    * Creates a random access byte stream to read from, and
    * write to, the bytes specified by the byte[] argument.
+   *
+   * @param bytes byte array to work with
    */
   public ByteArrayHandle(byte[] bytes) {
     buffer = ByteBuffer.wrap(bytes);
   }
 
+  /**
+   *
+   * Creates a random access byte stream to read from, and
+   * write to, the supplied ByteBuffer.
+   *
+   * @param bytes ByteBuffer used for reading and writing
+   */
   public ByteArrayHandle(ByteBuffer bytes) {
     buffer = bytes;
   }
@@ -86,7 +95,11 @@ public ByteArrayHandle() {
 
   // -- ByteArrayHandle API methods --
 
-  /** Gets the byte array backing this FileHandle. */
+  /**
+   * Gets a byte array representing the current state of this ByteArrayHandle.
+   *
+   * @return a byte array representation of the backing ByteBuffer
+   */
   public byte[] getBytes() {
     return buffer.array();
   }

src/main/java/loci/common/CBZip2InputStream.java

@@ -237,6 +237,8 @@ private void makeMaps() {
    * to skip the first two bytes. Otherwise this constructor will
    * throw an exception. </p>
    *
+   * @param in stream from which to read BZip2 data; expected to be
+   *   set to the first byte past the 2 byte magic marker
    * @throws IOException
    *   if the stream content is malformed or an I/O error occurs.
    * @throws NullPointerException

src/main/java/loci/common/DateTools.java

@@ -110,18 +110,53 @@ private DateTools() { }
   /**
    * Converts from two-word tick representation to milliseconds.
    * Mainly useful in conjunction with COBOL date conversion.
+   *
+   * @param hi the upper 32 bits of the tick count
+   * @param lo the lower 32 bits of the tick count
+   * @return the number of milliseconds corresponding to the tick count,
+   *         where 1 tick = 100 ns
    */
   public static long getMillisFromTicks(long hi, long lo) {
     long ticks = ((hi << 32) | lo);
     return ticks / 10000; // 100 ns = 0.0001 ms
   }
 
-  /** Converts the given timestamp into an ISO8601 date. */
+  /**
+   * Converts the given timestamp into an ISO8601 date.
+   *
+   * @param stamp the format-dependent timestamp
+   * @param format the format in which <code>stamp</code> is stored.
+   *               This is used to select the epoch value used for normalizing
+   *               the timestamp to milliseconds since the UNIX epoch.  Valid
+   *               values are #UNIX, #COBOL, #MICROSOFT, #ZVI, and #ALT_ZVI.
+   * @return an ISO 8601 formatted timestamp
+   * @see #UNIX_EPOCH
+   * @see #COBOL_EPOCH
+   * @see #MICROSOFT_EPOCH
+   * @see #ZVI_EPOCH
+   * @see #ALT_ZVI_EPOCH
+   */
   public static String convertDate(long stamp, int format) {
     return convertDate(stamp, format, ISO8601_FORMAT);
   }
 
-  /** Converts the given timestamp into a date string with the given format. */
+  /**
+   * Converts the given timestamp into a date string with the given format.
+   *
+   * @param stamp the format-dependent timestamp
+   * @param format the format in which <code>stamp</code> is stored.
+   *               This is used to select the epoch value used for normalizing
+   *               the timestamp to milliseconds since the UNIX epoch.  Valid
+   *               values are #UNIX, #COBOL, #MICROSOFT, #ZVI, and #ALT_ZVI.
+   * @param outputFormat the pattern used for formatting the timestamp
+   * @return a timestamp in the specified output format
+   * @see #UNIX_EPOCH
+   * @see #COBOL_EPOCH
+   * @see #MICROSOFT_EPOCH
+   * @see #ZVI_EPOCH
+   * @see #ALT_ZVI_EPOCH
+   * @see DateTimeFormat
+   */
   public static String convertDate(long stamp, int format, String outputFormat)
   {
     return convertDate(stamp, format, outputFormat, false);
@@ -132,6 +167,21 @@ public static String convertDate(long stamp, int format, String outputFormat)
    *
    * If correctTimeZoneForGMT is set, then the timestamp will be interpreted
    * as being relative to GMT and not the local time zone.
+   *
+   * @param stamp the format-dependent timestamp
+   * @param format the format in which <code>stamp</code> is stored.
+   *               This is used to select the epoch value used for normalizing
+   *               the timestamp to milliseconds since the UNIX epoch.  Valid
+   *               values are #UNIX, #COBOL, #MICROSOFT, #ZVI, and #ALT_ZVI.
+   * @param outputFormat the pattern used for formatting the timestamp
+   * @param correctTimeZoneForGMT true if the timestamp is relative to GMT
+   * @return a timestamp in the specified output format
+   * @see #UNIX_EPOCH
+   * @see #COBOL_EPOCH
+   * @see #MICROSOFT_EPOCH
+   * @see #ZVI_EPOCH
+   * @see #ALT_ZVI_EPOCH
+   * @see DateTimeFormat
    */
   public static String convertDate(long stamp, int format, String outputFormat,
     boolean correctTimeZoneForGMT)
@@ -181,6 +231,8 @@ public static String convertDate(long stamp, int format, String outputFormat,
    * @param date      The date to parse as a Joda timestamp
    * @param format    The date format to parse the string date
    * @param separator The separator for milliseconds
+   * @return the Joda Instant object representing the timestamp
+   * @see Instant
    */
   protected static Instant parseDate(String date, String format, String separator) {
 
@@ -244,6 +296,7 @@ protected static Instant parseDate(String date, String format, String separator)
    *
    * @param date   The date to format as ISO 8601
    * @param format The date format to parse the string date
+   * @return an ISO 8601 formatted timestamp
    */
   public static String formatDate(String date, String format) {
     return formatDate(date, format, false);
@@ -257,6 +310,7 @@ public static String formatDate(String date, String format) {
    * @param date      The date to format as ISO 8601
    * @param format    The date format to parse the string date
    * @param separator The separator for milliseconds
+   * @return an ISO 8601 formatted timestamp
    */
   public static String formatDate(String date, String format, String separator) {
     return formatDate(date, format, false, separator);
@@ -268,6 +322,7 @@ public static String formatDate(String date, String format, String separator) {
    * @param date    The date to format as ISO 8601.
    * @param format  The date format to parse the string date
    * @param lenient Whether or not to leniently parse the date.
+   * @return an ISO 8601 formatted timestamp
    */
   public static String formatDate(String date, String format, boolean lenient) {
    return formatDate(date, format, false, null);
@@ -280,6 +335,7 @@ public static String formatDate(String date, String format, boolean lenient) {
    * @param format    The date format to parse the string date
    * @param lenient   Whether or not to leniently parse the date.
    * @param separator The separator for milliseconds
+   * @return an ISO 8601 formatted timestamp
    */
   public static String formatDate(String date, String format, boolean lenient, String separator) {
     if (date == null) return null;
@@ -309,6 +365,7 @@ public static String formatDate(String date, String format, boolean lenient, Str
    *
    * @param date    The date to format as ISO 8601
    * @param formats The date possible formats to parse the string date
+   * @return an ISO 8601 formatted timestamp
    */
   public static String formatDate(String date, String[] formats) {
     return formatDate(date, formats, false, null);
@@ -323,6 +380,7 @@ public static String formatDate(String date, String[] formats) {
    * @param date    The date to format as ISO 8601.
    * @param formats The date possible formats to parse the string date
    * @param lenient Whether or not to leniently parse the date.
+   * @return an ISO 8601 formatted timestamp
    */
   public static String formatDate(String date, String[] formats,
     boolean lenient)
@@ -338,6 +396,7 @@ public static String formatDate(String date, String[] formats,
    * @param date    The date to format as ISO 8601
    * @param formats The date possible formats to parse the string date
    * @param separator  The separator for milliseconds
+   * @return an ISO 8601 formatted timestamp
    */
   public static String formatDate(String date, String[] formats, String separator) {
     return formatDate(date, formats, false, separator);
@@ -350,6 +409,7 @@ public static String formatDate(String date, String[] formats, String separator)
    * @param formats    The date possible formats to parse the string date
    * @param lenient    Whether or not to leniently parse the date.
    * @param separator  The separator for milliseconds
+   * @return an ISO 8601 formatted timestamp
    */
   public static String formatDate(String date, String[] formats,
     boolean lenient, String separator)
@@ -394,15 +454,15 @@ public static long getTime(String date, String format, String separator) {
   }
 
   /**
-   * Returns a timestamp for the current timezone in a
+   * @return a timestamp for the current timezone in a
    * human-readable locale-independent format ("YYYY-MM-DD HH:MM:SS")
    */
   public static String getTimestamp() {
     return TIMESTAMP_FORMATTER.print(new DateTime());
   }
 
   /**
-   * Returns a timestamp for the current timezone in a format suitable
+   * @return a timestamp for the current timezone in a format suitable
    * for a filename in a locale-independent format
    * ("YYYY-MM-DD_HH-MM-SS")
    */

src/main/java/loci/common/DebugTools.java

@@ -58,7 +58,12 @@ private DebugTools() { }
 
   // -- DebugTools methods --
 
-  /** Extracts the given exception's corresponding stack trace to a string. */
+  /**
+   * Extracts the given exception's corresponding stack trace to a string.
+   *
+   * @param t the Throwable from which to extract a stack trace
+   * @return the complete stack trace as a String
+   */
   public static String getStackTrace(Throwable t) {
     try {
       ByteArrayOutputStream out = new ByteArrayOutputStream();
@@ -179,6 +184,11 @@ public static synchronized boolean enableIJLogging(boolean debug) {
   /**
    * This method uses reflection to scan the values of the given class's
    * static fields, returning the first matching field's name.
+   *
+   * @param c the class to scan
+   * @param value the int value of the field to find
+   * @return the name of the field, or the string representation of
+   *         <code>value</code> if a matching field is not found
    */
   public static String getFieldName(Class<?> c, int value) {
     Field[] fields = c.getDeclaredFields();

src/main/java/loci/common/FileHandle.java

@@ -59,6 +59,10 @@ public class FileHandle implements IRandomAccess {
   /**
    * Creates a random access file stream to read from, and
    * optionally to write to, the file specified by the File argument.
+   *
+   * @param file a {@link File} representing a file on disk
+   * @param mode a valid access mode as defined in {@link RandomAccessFile}
+   * @throws FileNotFoundException if the file does not exist
    */
   public FileHandle(File file, String mode) throws FileNotFoundException {
     raf = new RandomAccessFile(file, mode);
@@ -67,14 +71,20 @@ public FileHandle(File file, String mode) throws FileNotFoundException {
   /**
    * Creates a random access file stream to read from, and
    * optionally to write to, a file with the specified name.
+   *
+   * @param name the path to a file on disk
+   * @param mode a valid access mode as defined in {@link RandomAccessFile}
+   * @throws FileNotFoundException if the file does not exist
    */
   public FileHandle(String name, String mode) throws FileNotFoundException {
     raf = new RandomAccessFile(name, mode);
   }
 
   // -- FileHandle API methods --
 
-  /** Gets the random access file object backing this FileHandle. */
+  /**
+   * @return the {@link RandomAccessFile} object backing this FileHandle.
+   */
   public RandomAccessFile getRandomAccessFile() { return raf; }
 
   // -- IRandomAccess API methods --

src/main/java/loci/common/GZipHandle.java

@@ -53,6 +53,7 @@ public class GZipHandle extends StreamHandle {
   /**
    * Construct a new GZipHandle for the given file.
    *
+   * @param file the path to the GZip file
    * @throws HandleException if the given file name is not a GZip file.
    */
   public GZipHandle(String file) throws IOException {
@@ -76,7 +77,11 @@ public GZipHandle(String file) throws IOException {
 
   // -- GZipHandle API methods --
 
-  /** Returns true if the given filename is a gzip file. */
+  /**
+   * @param file the path to the GZip file
+   * @return true if the given filename is a gzip file
+   * @throws IOException if the file cannot be read
+   */
   public static boolean isGZipFile(String file) throws IOException {
     if (!file.toLowerCase().endsWith(".gz")) return false;