ICU-5605 Added all remaining javadocs and renamed some variables.

X-SVN-Rev: 21268

icu4j/src/com/ibm/icu/dev/tool/tzu/GUILoader.java

@@ -320,30 +320,70 @@ public class GUILoader {
             }
     }
 
+    /**
+     * The thread that partakes in the searching and updating.
+     */
     private Thread workerThread = null;
 
+    /**
+     * Whether the paths frame has been closed or not.
+     */
     private boolean pathClosed = false;
 
+    /**
+     * Whether the results frame has been closed or not.
+     */
     private boolean resultClosed = true;
 
+    /**
+     * The path model that stores all the paths and takes care of searching.
+     */
     private PathModel pathModel;
 
-    private PathComponent pathGUI;
-
+    /**
+     * The result model that stores all the results and takes care of updating.
+     */
     private ResultModel resultModel;
 
+    /**
+     * The source model that stores all the update sources and accesses the
+     * repository for more sources.
+     */
     private SourceModel sourceModel;
 
+    /**
+     * The component that allows the user to interact with the path model.
+     */
+    private PathComponent pathGUI;
+
+    /**
+     * The component that allows the user to interact with the result model.
+     */
     private ResultComponent resultGUI;
 
+    /**
+     * The frame that displays the path model component (<code>pathGUI</code>).
+     */
     private JFrame pathFrame;
 
+    /**
+     * The frame that displays the result model component (<code>resultGUI</code>).
+     */
     private JFrame resultFrame;
 
+    /**
+     * The backup directory to store files.
+     */
     private File backupDir;
 
+    /**
+     * The tool's home directory.
+     */
     private File curDir;
 
+    /**
+     * The current logger.
+     */
     private Logger logger;
 
     /**

icu4j/src/com/ibm/icu/dev/tool/tzu/ICUFile.java

@@ -726,15 +726,33 @@ public class ICUFile {
     public static final String TZ_ENTRY_FILENAME = TZ_ENTRY_FILENAME_PREFIX
             + TZ_ENTRY_FILENAME_EXTENSION;
 
+    /**
+     * The buffer size to use for copying data.
+     */
     private static final int BUFFER_SIZE = 1024;
 
+    /**
+     * The ICU4J jar file represented by this ICUFile.
+     */
     private File icuFile;
 
+    /**
+     * The ICU version of the ICU4J jar.
+     */
     private String icuVersion;
 
+    /**
+     * The version of the timezone resource inside the ICU4J jar.
+     */
     private String tzVersion;
 
+    /**
+     * The entry for the timezone resource inside the ICU4J jar.
+     */
     private JarEntry tzEntry;
 
+    /**
+     * The current logger.
+     */
     private Logger logger;
 }

icu4j/src/com/ibm/icu/dev/tool/tzu/ICUJarFinder.java

@@ -16,6 +16,10 @@ import java.util.List;
  * Finds all updatable ICU4J jars in a set of specified directories.
  */
 public class ICUJarFinder {
+
+    /**
+     * An empty constructor that restricts construction.
+     */
     private ICUJarFinder() {
     }
 

icu4j/src/com/ibm/icu/dev/tool/tzu/IncludePath.java

@@ -68,7 +68,13 @@ public class IncludePath {
                 .equals(((IncludePath) other).path);
     }
 
+    /**
+     * The path represented by this IncludePath.
+     */
     private File path;
 
+    /**
+     * Whether to include or exclude the path represented by this IncludePath.
+     */
     private boolean include;
 }

icu4j/src/com/ibm/icu/dev/tool/tzu/Logger.java

@@ -16,7 +16,9 @@ import javax.swing.JOptionPane;
 
 /**
  * A singleton object that handles output to the screen and to a log file. Get
- * the current instance of the logger with <code>getInstance</code>,
+ * the current instance of the logger with <code>getInstance</code> and use
+ * the output functions to output to the screen, the log file, the status bar,
+ * and in dialog messages.
  */
 public class Logger {
 
@@ -39,9 +41,9 @@ public class Logger {
     private Logger(String filename, int verbosity, JLabel statusBar,
             Component dialogParent) throws FileNotFoundException {
         System.out.println("Log file: " + filename);
-        if (this.log != null)
-            this.log.close();
-        this.log = new PrintStream(new FileOutputStream(filename));
+        if (this.fileStream != null)
+            this.fileStream.close();
+        this.fileStream = new PrintStream(new FileOutputStream(filename));
         this.verbosity = verbosity;
         this.statusBar = statusBar;
         this.dialogParent = dialogParent;
@@ -50,7 +52,9 @@ public class Logger {
     /**
      * Gets the instance of the logger, constructing a new one with
      * <code>filename</code> and <code>verbosity</code> if one is not
-     * already constructed.
+     * already constructed. If a statusbar is given, status messages will be
+     * sent to it. If a dialogParent is specified, dialog messages will be
+     * displayed.
      * 
      * @param filename
      *            The filename to use for logging output.
@@ -174,8 +178,8 @@ public class Logger {
      *            The message to print.
      */
     public void logToFile(String message) {
-        if (log != null)
-            log.print(message);
+        if (fileStream != null)
+            fileStream.print(message);
     }
 
     /**
@@ -185,8 +189,8 @@ public class Logger {
      *            The message to print.
      */
     public void loglnToFile(String message) {
-        if (log != null)
-            log.println(message);
+        if (fileStream != null)
+            fileStream.println(message);
     }
 
     /**
@@ -244,8 +248,8 @@ public class Logger {
      */
     public void error(String message) {
         System.err.print(message);
-        if (log != null)
-            log.print(message);
+        if (fileStream != null)
+            fileStream.print(message);
     }
 
     /**
@@ -257,8 +261,8 @@ public class Logger {
      */
     public void errorln(String message) {
         System.err.println(message);
-        if (log != null)
-            log.println(message);
+        if (fileStream != null)
+            fileStream.println(message);
     }
 
     /**
@@ -319,13 +323,28 @@ public class Logger {
      */
     public static final String DEFAULT_FILENAME = "icutzu.log";
 
+    /**
+     * The verbosity of the logger.
+     */
     private int verbosity = NORMAL;
 
-    private PrintStream log = null;
+    /**
+     * The means of output to the log file.
+     */
+    private PrintStream fileStream = null;
 
+    /**
+     * The status bar to display status messages.
+     */
     private JLabel statusBar = null;
 
+    /**
+     * The parent to use when displaying a dialog.
+     */
     private Component dialogParent = null;
 
+    /**
+     * The single instance of the logger.
+     */
     private static Logger logger = null;
 }

icu4j/src/com/ibm/icu/dev/tool/tzu/PathComponent.java

@@ -168,10 +168,23 @@ public class PathComponent extends JComponent {
         });
     }
 
+    /**
+     * Returns whether the user has specified to include or to exclude the
+     * entered path.
+     * 
+     * @return Whether the user has specified to include or to exclude the
+     *         entered path.
+     */
     private boolean isIncluded() {
         return ((String) pathSignBox.getSelectedItem()).equals("Include");
     }
 
+    /**
+     * Attempts to add a path to the path model.
+     * 
+     * @param file
+     *            The path to add.
+     */
     private void addFile(File file) {
         if (!pathModel.add(new IncludePath(file, isIncluded())))
             JOptionPane.showMessageDialog(PathComponent.this, "\""
@@ -200,43 +213,102 @@ public class PathComponent extends JComponent {
         pathList.setModel(pathModel);
     }
 
+    /**
+     * The panel to hold the input components.
+     */
     private JPanel pathInputPanel = new JPanel();
 
+    /**
+     * The panel to hold the output components.
+     */
     private JPanel pathOptionPanel = new JPanel();
 
+    /**
+     * The panel to hold the search components.
+     */
     private JPanel pathSearchPanel = new JPanel();
 
+    /**
+     * The JList that holds the path model.
+     */
     private JList pathList = new JList();
 
+    /**
+     * The combobox where a user specifies whether to include or to exclude an
+     * entered path.
+     */
     private JComboBox pathSignBox = new JComboBox(new Object[] { "Include",
             "Exclude" });
 
+    /**
+     * The field where the user can enter a path.
+     */
     private JTextField pathField = new JTextField(30);
 
+    /**
+     * The checkbox where the user can specify whether or not to search
+     * subdirectories. Set to true by default.
+     */
     private JCheckBox pathSubdirOption = new JCheckBox("Search Subdirectories",
             true);
 
+    /**
+     * The browse button where the user can browse for a particular path.
+     */
     private JButton pathBrowseButton = new JButton("Browse...");
 
+    /**
+     * The search button that starts the search on the selected paths (or all
+     * the paths if none are selected).
+     */
     private JButton pathSearchButton = new JButton("Search");
 
+    /**
+     * The browse dialog that pops up when the browse button is clicked.
+     */
     private JFileChooser pathChooser = new JFileChooser();
 
+    /**
+     * The context menu for extra options.
+     */
     private JPopupMenu pathPopup = new JPopupMenu();
 
+    /**
+     * A menu item for <code>pathPopup</code> to add all drives to the path
+     * model.
+     */
     private JMenuItem pathAddAllDrivesItem = new JMenuItem(
             "Add All Drives to List");
 
+    /**
+     * A menu item for <code>pathPopup</code> to remove the selected paths
+     * from the path model.
+     */
     private JMenuItem pathRemoveSelectedItem = new JMenuItem(
             "Remove Selected Items");
 
+    /**
+     * A menu item for <code>pathPopup</code> to remove all paths from the
+     * path model.
+     */
     private JMenuItem pathRemoveAllItem = new JMenuItem("Remove All");
 
+    /**
+     * A menu item for <code>pathPopup</code> to begin a search on all paths
+     * in the path model.
+     */
     private JMenuItem pathSearchSelectedItem = new JMenuItem(
             "Search Selected Items");
 
+    /**
+     * A menu item for <code>pathPopup</code> to begin a search on the
+     * selected paths in the path model.
+     */
     private JMenuItem pathSearchAllItem = new JMenuItem("Search All");
 
+    /**
+     * The path model that stores all the paths.
+     */
     private PathModel pathModel;
 
     /**

icu4j/src/com/ibm/icu/dev/tool/tzu/PathModel.java

@@ -35,8 +35,8 @@ class PathModel extends AbstractListModel {
      */
     public PathModel(Logger logger, File pathFile) {
         this.logger = logger;
-        this.pathFile = pathFile;
-        this.pathFilename = pathFile.getName();
+        this.pathListFile = pathFile;
+        this.pathListFilename = pathFile.getName();
     }
 
     /**
@@ -237,8 +237,8 @@ class PathModel extends AbstractListModel {
      * @throws IllegalArgumentException
      */
     public void loadPaths() throws IOException, IllegalArgumentException {
-        logger.printlnToScreen("Scanning " + pathFilename + " file...");
-        logger.printlnToScreen(pathFilename + " file contains");
+        logger.printlnToScreen("Scanning " + pathListFilename + " file...");
+        logger.printlnToScreen(pathListFilename + " file contains");
 
         BufferedReader reader = null;
         int lineNumber = 1;
@@ -246,7 +246,7 @@ class PathModel extends AbstractListModel {
         char sign;
 
         try {
-            reader = new BufferedReader(new FileReader(pathFile));
+            reader = new BufferedReader(new FileReader(pathListFile));
             while (reader.ready()) {
                 line = reader.readLine().trim();
 
@@ -270,9 +270,9 @@ class PathModel extends AbstractListModel {
                 lineNumber++;
             }
         } catch (FileNotFoundException ex) {
-            pathListError("The " + pathFilename + " file doesn't exist.");
+            pathListError("The " + pathListFilename + " file doesn't exist.");
         } catch (IOException ex) {
-            pathListError("Could not read the " + pathFilename + " file.");
+            pathListError("Could not read the " + pathListFilename + " file.");
         } finally {
             try {
                 if (reader != null)
@@ -294,7 +294,7 @@ class PathModel extends AbstractListModel {
      */
     private void pathListError(String message, int lineNumber)
             throws IllegalArgumentException {
-        throw new IllegalArgumentException("Error in " + pathFilename
+        throw new IllegalArgumentException("Error in " + pathListFilename
                 + " (line " + lineNumber + "): " + message);
     }
 
@@ -306,15 +306,27 @@ class PathModel extends AbstractListModel {
      * @throws IOException
      */
     private void pathListError(String message) throws IOException {
-        throw new IOException("Error in " + pathFilename + ": " + message);
+        throw new IOException("Error in " + pathListFilename + ": " + message);
     }
 
-    private String pathFilename;
+    /**
+     * The filename of the paths file where the paths are stored.
+     */
+    private String pathListFilename;
 
-    private File pathFile;
+    /**
+     * The paths file where the paths are stored.
+     */
+    private File pathListFile;
 
-    private List list = new ArrayList(); // list of paths (Files)
+    /**
+     * The list of paths as IncludePaths.
+     */
+    private List list = new ArrayList();
 
+    /**
+     * The current logger.
+     */
     private Logger logger;
 
     /**

icu4j/src/com/ibm/icu/dev/tool/tzu/ResultComponent.java

@@ -262,49 +262,119 @@ public class ResultComponent extends JComponent {
         resultSourceList.setModel(sourceModel);
     }
 
+    /**
+     * The panel where input components are shown.
+     */
     private JPanel resultInputPanel = new JPanel();
 
+    /**
+     * The panel where status components are shown.
+     */
     private JPanel resultStatusPanel = new JPanel();
 
+    /**
+     * The panel where option components are shown.
+     */
     private JPanel resultOptionPanel = new JPanel();
 
+    /**
+     * The panel where update components are shown.
+     */
     private JPanel resultUpdatePanel = new JPanel();
 
+    /**
+     * The table where the result model is shown.
+     */
     private JTable resultTable = new JTable();
 
+    /**
+     * The field where an ICU4J jar file can be directly added.
+     */
     private JTextField resultField = new JTextField(30);
 
+    /**
+     * The checkbox for whether files that are either unreadable or unwritable
+     * are displayed (and likewise updated).
+     */
     private JCheckBox resultHideOption = new JCheckBox(
-            "Hide Unreadable/Unwritable Files", true);
+            "Hide Unreadable and Unwritable Files", true);
 
+    /**
+     * A browse button to add specific results.
+     */
     private JButton resultBrowseButton = new JButton("Browse...");
 
+    /**
+     * An update button to update the selected files, or all files if none are
+     * selected.
+     */
     private JButton resultUpdateButton = new JButton("Update");
 
+    /**
+     * A cancel update button to cancel an update if one is currently occuring.
+     */
     private JButton resultCancelUpdateButton = new JButton("Cancel Update");
 
+    /**
+     * A cancel search button to cancel a search if one is currently occuring.
+     */
     private JButton resultCancelSearchButton = new JButton("Cancel Search");
 
+    /**
+     * The dialog that comes up when the browse button is clicked.
+     */
     private JFileChooser resultChooser = new JFileChooser();
 
+    /**
+     * The context menu that pops up with more options.
+     */
     private JPopupMenu resultPopup = new JPopupMenu();
 
+    /**
+     * A menu item for <code>pathPopup</code> to remove the selected files
+     * from the result model.
+     */
     private JMenuItem resultRemoveSelectedItem = new JMenuItem(
             "Remove Selected Items");
 
+    /**
+     * A menu item for <code>pathPopup</code> to remove all files from the
+     * result model.
+     */
     private JMenuItem resultRemoveAllItem = new JMenuItem("Remove All");
 
+    /**
+     * A menu item for <code>pathPopup</code> to update the selected files in
+     * the result model.
+     */
     private JMenuItem resultUpdateSelectedItem = new JMenuItem(
             "Update Selected Items");
 
+    /**
+     * A menu item for <code>pathPopup</code> to update all files in the
+     * result model.
+     */
     private JMenuItem resultUpdateAllItem = new JMenuItem("Update All");
 
+    /**
+     * The combobox for choosing which timezone resource on the web to use in an
+     * update.
+     */
     private JComboBox resultSourceList = new JComboBox();
 
+    /**
+     * The model for all the results from a search.
+     */
     private ResultModel resultModel;
 
+    /**
+     * The model for all the timezone resources on the web.
+     */
     private SourceModel sourceModel;
 
+    /**
+     * The status bar for status messages.
+     */
     private JLabel statusBar = new JLabel();
 
     /**