Doc: improve javadoc

git-svn-id: http://svn.code.sf.net/p/davmail/code/trunk@697 3d1905a2-6b24-0410-a738-b14d5a86fcbd

src/java/davmail/exchange/ExchangeSession.java

@@ -1102,7 +1102,6 @@ public class ExchangeSession {
         public boolean noInferiors;
         /**
          * Requested folder name
-         * TODO : same as folderPath ?
          */
         public String folderName;
         /**

src/java/davmail/exchange/XMLStreamUtil.java

@@ -34,6 +34,11 @@ public final class XMLStreamUtil {
     private XMLStreamUtil() {
     }
 
+    /**
+     * Build a new XMLInputFactory.
+     *
+     * @return XML input factory
+     */
     public static XMLInputFactory getXmlInputFactory() {
         XMLInputFactory inputFactory = XMLInputFactory.newInstance();
         inputFactory.setProperty(XMLInputFactory.IS_COALESCING, Boolean.TRUE);
@@ -41,6 +46,16 @@ public final class XMLStreamUtil {
         return inputFactory;
     }
 
+    /**
+     * Convert the XML stream to a map of entries.
+     * An entry is also a key/value map
+     *
+     * @param inputStream xml input stream
+     * @param rowName     xml tag name of entries
+     * @param idName      xml tag name of entry attribute used as key in the main map
+     * @return map of entries
+     * @throws IOException on error
+     */
     public static Map<String, Map<String, String>> getElementContentsAsMap(InputStream inputStream, String rowName, String idName) throws IOException {
         Map<String, Map<String, String>> results = new HashMap<String, Map<String, String>>();
         Map<String, String> item = null;

src/java/davmail/ui/tray/AwtGatewayTray.java

@@ -56,10 +56,18 @@ public class AwtGatewayTray implements DavGatewayTrayInterface {
     protected static LogBrokerMonitor logBrokerMonitor;
     private boolean isActive = true;
 
+    /**
+     * Return AWT Image icon for frame title.
+     *
+     * @return frame icon
+     */
     public Image getFrameIcon() {
         return image;
     }
 
+    /**
+     * Switch tray icon between active and standby icon.
+     */
     public void switchIcon() {
         isActive = true;
         SwingUtilities.invokeLater(new Runnable() {
@@ -73,6 +81,9 @@ public class AwtGatewayTray implements DavGatewayTrayInterface {
         });
     }
 
+    /**
+     * Set tray icon to inactive (network down)
+     */
     public void resetIcon() {
         SwingUtilities.invokeLater(new Runnable() {
             public void run() {
@@ -81,6 +92,9 @@ public class AwtGatewayTray implements DavGatewayTrayInterface {
         });
     }
 
+    /**
+     * Set tray icon to inactive (network down)
+     */
     public void inactiveIcon() {
         isActive = false;
         SwingUtilities.invokeLater(new Runnable() {
@@ -90,10 +104,21 @@ public class AwtGatewayTray implements DavGatewayTrayInterface {
         });
     }
 
+    /**
+     * Check if current tray status is inactive (network down).
+     *
+     * @return true if inactive
+     */
     public boolean isActive() {
         return isActive;
     }
 
+    /**
+     * Display balloon message for log level.
+     *
+     * @param message text message
+     * @param level   log level
+     */
     public void displayMessage(final String message, final Level level) {
         SwingUtilities.invokeLater(new Runnable() {
             public void run() {
@@ -115,6 +140,9 @@ public class AwtGatewayTray implements DavGatewayTrayInterface {
         });
     }
 
+    /**
+     * Open about window
+     */
     public void about() {
         SwingUtilities.invokeLater(new Runnable() {
             public void run() {
@@ -124,6 +152,9 @@ public class AwtGatewayTray implements DavGatewayTrayInterface {
         });
     }
 
+    /**
+     * Open settings window
+     */
     public void preferences() {
         SwingUtilities.invokeLater(new Runnable() {
             public void run() {
@@ -133,6 +164,9 @@ public class AwtGatewayTray implements DavGatewayTrayInterface {
         });
     }
 
+    /**
+     * Create tray icon and register frame listeners.
+     */
     public void init() {
         SwingUtilities.invokeLater(new Runnable() {
             public void run() {

src/java/davmail/ui/tray/DavGatewayTray.java

@@ -41,6 +41,11 @@ public class DavGatewayTray {
 
     static DavGatewayTrayInterface davGatewayTray;
 
+    /**
+     * Return AWT Image icon for frame title.
+     *
+     * @return frame icon
+     */
     public static Image getFrameIcon() {
         Image icon = null;
         if (davGatewayTray != null) {
@@ -49,22 +54,39 @@ public class DavGatewayTray {
         return icon;
     }
 
+    /**
+     * Switch tray icon between active and standby icon.
+     */
     public static void switchIcon() {
         if (davGatewayTray != null) {
             davGatewayTray.switchIcon();
         }
     }
 
+    /**
+     * Set tray icon to inactive (network down)
+     */
     public static void resetIcon() {
         if (davGatewayTray != null && isActive()) {
             davGatewayTray.resetIcon();
         }
     }
 
+    /**
+     * Check if current tray status is inactive (network down).
+     *
+     * @return true if inactive
+     */
     public static boolean isActive() {
         return davGatewayTray == null || davGatewayTray.isActive();
     }
 
+    /**
+     * Log and display balloon message according to log level.
+     *
+     * @param message text message
+     * @param level   log level
+     */
     protected static void displayMessage(BundleMessage message, Level level) {
         LOGGER.log(level, message.formatLog());
         if (davGatewayTray != null) {
@@ -72,6 +94,13 @@ public class DavGatewayTray {
         }
     }
 
+    /**
+     * Log and display balloon message and exception according to log level.
+     *
+     * @param message text message
+     * @param e       exception
+     * @param level   log level
+     */
     protected static void displayMessage(BundleMessage message, Exception e, Level level) {
         if (e instanceof NetworkDownException) {
             LOGGER.log(level, BundleMessage.getExceptionLogMessage(message, e));
@@ -87,26 +116,57 @@ public class DavGatewayTray {
         }
     }
 
+    /**
+     * Log message at level DEBUG.
+     *
+     * @param message bundle message
+     */
     public static void debug(BundleMessage message) {
         displayMessage(message, Level.DEBUG);
     }
 
+    /**
+     * Log message at level INFO.
+     *
+     * @param message bundle message
+     */
     public static void info(BundleMessage message) {
         displayMessage(message, Level.INFO);
     }
 
+    /**
+     * Log message at level WARN.
+     *
+     * @param message bundle message
+     */
     public static void warn(BundleMessage message) {
         displayMessage(message, Level.WARN);
     }
 
+    /**
+     * Log exception at level WARN.
+     *
+     * @param e exception
+     */
     public static void warn(Exception e) {
         displayMessage(null, e, Level.WARN);
     }
 
+    /**
+     * Log message at level ERROR.
+     *
+     * @param message bundle message
+     */
     public static void error(BundleMessage message) {
         displayMessage(message, Level.ERROR);
     }
 
+    /**
+     * Log exception at level WARN for NetworkDownException,
+     * ERROR for other exceptions.
+     *
+     * @param e exception
+     */
     public static void log(Exception e) {
         // only warn on network down
         if (e instanceof NetworkDownException) {
@@ -116,22 +176,48 @@ public class DavGatewayTray {
         }
     }
 
+    /**
+     * Log exception at level ERROR.
+     *
+     * @param e exception
+     */
     public static void error(Exception e) {
         displayMessage(null, e, Level.ERROR);
     }
 
+    /**
+     * Log message and exception at level DEBUG.
+     *
+     * @param message bundle message
+     * @param e       exception
+     */
     public static void debug(BundleMessage message, Exception e) {
         displayMessage(message, e, Level.DEBUG);
     }
 
+    /**
+     * Log message and exception at level WARN.
+     *
+     * @param message bundle message
+     * @param e       exception
+     */
     public static void warn(BundleMessage message, Exception e) {
         displayMessage(message, e, Level.WARN);
     }
 
+    /**
+     * Log message and exception at level ERROR.
+     *
+     * @param message bundle message
+     * @param e       exception
+     */
     public static void error(BundleMessage message, Exception e) {
         displayMessage(message, e, Level.ERROR);
     }
 
+    /**
+     * Create tray icon and register frame listeners.
+     */
     public static void init() {
         if (!Settings.getBooleanProperty("davmail.server")) {
             ClassLoader classloader = DavGatewayTray.class.getClassLoader();

src/java/davmail/ui/tray/DavGatewayTrayInterface.java

@@ -26,17 +26,45 @@ import java.awt.*;
  * Gateway tray interface common to SWT and pure java implementations
  */
 public interface DavGatewayTrayInterface {
+    /**
+     * Switch tray icon between active and standby icon.
+     */
     void switchIcon();
 
+    /**
+     * Reset tray icon to standby
+     */
     void resetIcon();
 
+    /**
+     * Set tray icon to inactive (network down)
+     */
     void inactiveIcon();
 
+    /**
+     * Check if current tray status is inactive (network down).
+     *
+     * @return true if inactive
+     */
     boolean isActive();
 
+    /**
+     * Return AWT Image icon for frame title.
+     *
+     * @return frame icon
+     */
     Image getFrameIcon();
 
+    /**
+     * Display balloon message for log level.
+     *
+     * @param message text message
+     * @param level   log level
+     */
     void displayMessage(String message, Level level);
 
+    /**
+     * Create tray icon and register frame listeners.
+     */
     void init();
 }

src/java/davmail/ui/tray/FrameGatewayTray.java

@@ -53,10 +53,18 @@ public class FrameGatewayTray implements DavGatewayTrayInterface {
     private static Image inactiveImage;
     private boolean isActive = true;
 
+    /**
+     * Return AWT Image icon for frame title.
+     *
+     * @return frame icon
+     */
     public Image getFrameIcon() {
         return image;
     }
 
+    /**
+     * Switch tray icon between active and standby icon.
+     */
     public void switchIcon() {
         isActive = true;
         SwingUtilities.invokeLater(new Runnable() {
@@ -70,6 +78,9 @@ public class FrameGatewayTray implements DavGatewayTrayInterface {
         });
     }
 
+    /**
+     * Set tray icon to inactive (network down)
+     */
     public void resetIcon() {
         SwingUtilities.invokeLater(new Runnable() {
             public void run() {
@@ -78,6 +89,9 @@ public class FrameGatewayTray implements DavGatewayTrayInterface {
         });
     }
 
+    /**
+     * Set tray icon to inactive (network down)
+     */
     public void inactiveIcon() {
         isActive = false;
         SwingUtilities.invokeLater(new Runnable() {
@@ -87,10 +101,21 @@ public class FrameGatewayTray implements DavGatewayTrayInterface {
         });
     }
 
+    /**
+     * Check if current tray status is inactive (network down).
+     *
+     * @return true if inactive
+     */
     public boolean isActive() {
         return isActive;
     }
 
+    /**
+     * Log and display balloon message according to log level.
+     *
+     * @param message text message
+     * @param level   log level
+     */
     public void displayMessage(final String message, final Level level) {
         SwingUtilities.invokeLater(new Runnable() {
             public void run() {
@@ -111,6 +136,9 @@ public class FrameGatewayTray implements DavGatewayTrayInterface {
         });
     }
 
+    /**
+     * Open about window
+     */
     public void about() {
         SwingUtilities.invokeLater(new Runnable() {
             public void run() {
@@ -120,6 +148,9 @@ public class FrameGatewayTray implements DavGatewayTrayInterface {
         });
     }
 
+    /**
+     * Open settings window
+     */
     public void preferences() {
         SwingUtilities.invokeLater(new Runnable() {
             public void run() {
@@ -129,6 +160,9 @@ public class FrameGatewayTray implements DavGatewayTrayInterface {
         });
     }
 
+    /**
+     * Open logging window.
+     */
     public void showLogs() {
         Logger rootLogger = Logger.getRootLogger();
         LF5Appender lf5Appender = (LF5Appender) rootLogger.getAppender("LF5Appender");
@@ -146,6 +180,9 @@ public class FrameGatewayTray implements DavGatewayTrayInterface {
         lf5Appender.getLogBrokerMonitor().show();
     }
 
+    /**
+     * Create tray icon and register frame listeners.
+     */
     public void init() {
         SwingUtilities.invokeLater(new Runnable() {
             public void run() {
@@ -196,13 +233,13 @@ public class FrameGatewayTray implements DavGatewayTrayInterface {
         ActionListener exitListener = new ActionListener() {
             public void actionPerformed(ActionEvent e) {
                 try {
-                DavGateway.stop();
+                    DavGateway.stop();
-                // dispose frames
+                    // dispose frames
-                settingsFrame.dispose();
+                    settingsFrame.dispose();
-                aboutFrame.dispose();
+                    aboutFrame.dispose();
-                if (logBrokerMonitor != null) {
+                    if (logBrokerMonitor != null) {
-                    logBrokerMonitor.dispose();
+                        logBrokerMonitor.dispose();
-                }
+                    }
                 } catch (Exception exc) {
                     DavGatewayTray.error(exc);
                 }

src/java/davmail/ui/tray/OSXAwtGatewayTray.java

@@ -26,6 +26,11 @@ import davmail.DavGateway;
  * Extended Awt tray with OSX extensions.
  */
 public class OSXAwtGatewayTray extends AwtGatewayTray {
+    /**
+     * Exit DavMail Gateway.
+     *
+     * @return true
+     */
     @SuppressWarnings({"SameReturnValue"})
     public boolean quit() {
         DavGateway.stop();

src/java/davmail/ui/tray/OSXFrameGatewayTray.java

@@ -31,6 +31,11 @@ import java.awt.event.ActionListener;
  */
 public class OSXFrameGatewayTray extends FrameGatewayTray {
 
+    /**
+     * Exit DavMail Gateway.
+     *
+     * @return true
+     */
     @SuppressWarnings({"SameReturnValue"})
     public boolean quit() {
         DavGateway.stop();

src/java/davmail/ui/tray/SwtGatewayTray.java

@@ -56,10 +56,18 @@ public class SwtGatewayTray implements DavGatewayTrayInterface {
 
     private final Thread mainThread = Thread.currentThread();
 
+    /**
+     * Return AWT Image icon for frame title.
+     *
+     * @return frame icon
+     */
     public java.awt.Image getFrameIcon() {
         return awtImage;
     }
 
+    /**
+     * Switch tray icon between active and standby icon.
+     */
     public void switchIcon() {
         isActive = true;
         display.syncExec(new Runnable() {
@@ -74,6 +82,9 @@ public class SwtGatewayTray implements DavGatewayTrayInterface {
 
     }
 
+    /**
+     * Set tray icon to inactive (network down)
+     */
     public void resetIcon() {
         display.syncExec(new Runnable() {
             public void run() {
@@ -82,6 +93,9 @@ public class SwtGatewayTray implements DavGatewayTrayInterface {
         });
     }
 
+    /**
+     * Set tray icon to inactive (network down)
+     */
     public void inactiveIcon() {
         isActive = false;
         display.syncExec(new Runnable() {
@@ -91,10 +105,21 @@ public class SwtGatewayTray implements DavGatewayTrayInterface {
         });
     }
 
+    /**
+     * Check if current tray status is inactive (network down).
+     *
+     * @return true if inactive
+     */
     public boolean isActive() {
         return isActive;
     }
 
+    /**
+     * Log and display balloon message according to log level.
+     *
+     * @param message text message
+     * @param level   log level
+     */
     public void displayMessage(final String message, final Level level) {
         if (trayItem != null) {
             display.asyncExec(new Runnable() {
@@ -138,13 +163,16 @@ public class SwtGatewayTray implements DavGatewayTrayInterface {
         return result;
     }
 
+    /**
+     * Create tray icon and register frame listeners.
+     */
     public void init() {
         // set native look and feel
         try {
             String lafClassName = UIManager.getSystemLookAndFeelClassName();
             // workaround for bug when SWT and AWT both try to access Gtk
             if (lafClassName.indexOf("gtk") > 0) {
-                    lafClassName = UIManager.getCrossPlatformLookAndFeelClassName();
+                lafClassName = UIManager.getCrossPlatformLookAndFeelClassName();
             }
             UIManager.setLookAndFeel(lafClassName);
         } catch (Exception e) {