JAL-3261 tidy up get/set properties in Cache, Javadoc, tests

[jalview.git] / src / jalview / util / Format.java

diff --git a/src/jalview/util/Format.java b/src/jalview/util/Format.java
index ce7ab6d..0f12eb8 100755 (executable)
--- a/src/jalview/util/Format.java
+++ b/src/jalview/util/Format.java
@@ -29,10 +29,13 @@ package jalview.util;
 import java.util.Arrays;
 
 /**
- * DOCUMENT ME!
+ * A utility class that provides a variety of formatting methods.
  * 
- * @author $author$
- * @version $Revision$
+ * Principle method {@code format} formats the number following printf
+ * conventions. Main limitation: Can only handle one format parameter at a time
+ * Use multiple Format objects to format more than one number
+ * 
+ * @author unknown
  */
 public class Format
 {
@@ -59,12 +62,59 @@ public class Format
   private final String formatString;
 
   /**
-   * Creates a new Format object.
+   * Creates a new Format object given a format descriptor, which follows printf
+   * conventions The string has a prefix, a format code and a suffix. The prefix
+   * and suffix become part of the formatted output. The format code directs the
+   * formatting of the (single) parameter to be formatted. The code has the
+   * following structure
+   * <ul>
+   * <li>a % (required)
+   * <li>a modifier (optional)
+   * <dl>
+   * <dt>+
+   * <dd>forces display of + for positive numbers
+   * <dt>0
+   * <dd>show leading zeroes
+   * <dt>-
+   * <dd>align left in the field
+   * <dt>space
+   * <dd>prepend a space in front of positive numbers
+   * <dt>#
+   * <dd>use "alternate" format. Add 0 or 0x for octal or hexadecimal numbers.
+   * Don't suppress trailing zeroes in general floating point format.
+   * </dl>
+   * <li>an integer denoting field width (optional)
+   * <li>a period followed by an integer denoting precision (optional)
+   * <li>a format descriptor (required)
+   * <dl>
+   * <dt>f
+   * <dd>floating point number in fixed format
+   * <dt>e, E
+   * <dd>floating point number in exponential notation (scientific format). The
+   * E format results in an uppercase E for the exponent (1.14130E+003), the e
+   * format in a lowercase e.
+   * <dt>g, G
+   * <dd>floating point number in general format (fixed format for small
+   * numbers, exponential format for large numbers). Trailing zeroes are
+   * suppressed. The G format results in an uppercase E for the exponent (if
+   * any), the g format in a lowercase e.
+   * <dt>d, i
+   * <dd>integer in decimal
+   * <dt>x
+   * <dd>integer in hexadecimal
+   * <dt>o
+   * <dd>integer in octal
+   * <dt>s
+   * <dd>string
+   * <dt>c
+   * <dd>character
+   * </dl>
+   * </ul>
    * 
    * @param s
-   *          DOCUMENT ME!
+   *          the format descriptor
    */
-  public Format(String s)
+  public Format(final String s)
   {
     formatString = s;
     width = 0;
@@ -214,63 +264,11 @@ public class Format
   }
 
   /**
-   * Formats the number following printf conventions. Main limitation: Can only
-   * handle one format parameter at a time Use multiple Format objects to format
-   * more than one number
-   * 
-   * @param s
-   *          the format string following printf conventions The string has a
-   *          prefix, a format code and a suffix. The prefix and suffix become
-   *          part of the formatted output. The format code directs the
-   *          formatting of the (single) parameter to be formatted. The code has
-   *          the following structure
-   *          <ul>
-   *          <li>a % (required)
-   *          <li>a modifier (optional)
-   *          <dl>
-   *          <dt>+
-   *          <dd>forces display of + for positive numbers
-   *          <dt>0
-   *          <dd>show leading zeroes
-   *          <dt>-
-   *          <dd>align left in the field
-   *          <dt>space
-   *          <dd>prepend a space in front of positive numbers
-   *          <dt>#
-   *          <dd>use "alternate" format. Add 0 or 0x for octal or hexadecimal
-   *          numbers. Don't suppress trailing zeroes in general floating point
-   *          format.
-   *          </dl>
-   *          <li>an integer denoting field width (optional)
-   *          <li>a period followed by an integer denoting precision (optional)
-   *          <li>a format descriptor (required)
-   *          <dl>
-   *          <dt>f
-   *          <dd>floating point number in fixed format
-   *          <dt>e, E
-   *          <dd>floating point number in exponential notation (scientific
-   *          format). The E format results in an uppercase E for the exponent
-   *          (1.14130E+003), the e format in a lowercase e.
-   *          <dt>g, G
-   *          <dd>floating point number in general format (fixed format for
-   *          small numbers, exponential format for large numbers). Trailing
-   *          zeroes are suppressed. The G format results in an uppercase E for
-   *          the exponent (if any), the g format in a lowercase e.
-   *          <dt>d, i
-   *          <dd>integer in decimal
-   *          <dt>x
-   *          <dd>integer in hexadecimal
-   *          <dt>o
-   *          <dd>integer in octal
-   *          <dt>s
-   *          <dd>string
-   *          <dt>c
-   *          <dd>character
-   *          </dl>
-   *          </ul>
-   * @exception IllegalArgumentException
-   *              if bad format
+   * Returns a 6 character string consisting of the hex values of the colour's
+   * rgb values (left padded with zeroes if necessary)
    * 
+   * @param color
+   * @return
    */
   public static String getHexString(java.awt.Color color)
   {