Bug 3502 - Improve javadoc support in Eclipse.

Added more comments. Source files are now added to Ice.jar and Freeze.jar.

9 files changed, 223 insertions, 106 deletions

diff --git a/CHANGES b/CHANGES
index 49aa8edb407..48acb5e3684 100644
--- a/CHANGES
+++ b/CHANGES
@@ -176,10 +176,14 @@ C++ Changes
 Java Changes
 ============
 
-- slice2java now preserves javadoc comments that apprear in the Slice
+- slice2java now preserves javadoc comments that appear in the Slice
   source and writes them through to the corresponding APIs in the
   generated code.
 
+- Ice.jar and Freeze.jar now include source files. This allows
+  IDEs such Eclipse to browse the Ice source code and to display
+  javadoc comments.
+
 - The following APIs are deprecated and will be removed in a future 
   release.
 
diff --git a/java/build.xml b/java/build.xml
index 46384edb696..2b1efdee71f 100644
--- a/java/build.xml
+++ b/java/build.xml
@@ -199,6 +199,18 @@
                 <attribute name="Built-By" value="ZeroC, Inc."/>
             </manifest>
         </jar>
+        <jar jarfile="${lib.dir}/Ice.jar" basedir="${src.dir}" update="yes">
+            <include name="**/*.java"/>
+            <exclude name="Freeze/**"/>
+            <exclude name="IceGridGUI/**"/>
+            <exclude name="test/**"/>
+            <exclude name="ant/**"/>
+            <exclude name="*/.jar"/>
+        </jar>
+        <jar jarfile="${lib.dir}/Ice.jar" basedir="${generated.dir}" update="yes">
+            <include name="**/*.java"/>
+            <exclude name="Freeze/**"/>
+        </jar>
     </target>
 
     <target name="freeze-compile" depends="ice-compile">
@@ -220,6 +232,12 @@
                 <attribute name="Class-Path" value="db.jar db-${db.version}.jar /usr/share/java/db-${db.version}.jar ../db.jar"/>
             </manifest>
         </jar>
+        <jar jarfile="${lib.dir}/Freeze.jar" basedir="${src.dir}" update="yes">
+            <include name="Freeze/**"/>
+        </jar>
+        <jar jarfile="${lib.dir}/Freeze.jar" basedir="${generated.dir}" update="yes">
+            <include name="Freeze/**"/>
+        </jar>
     </target>
 
     <target name="test-generate" depends="tasks, task-init">
diff --git a/java/src/Freeze/NavigableMap.java b/java/src/Freeze/NavigableMap.java
index 42e8960453d..5fa74412157 100644
--- a/java/src/Freeze/NavigableMap.java
+++ b/java/src/Freeze/NavigableMap.java
@@ -112,7 +112,15 @@ public interface NavigableMap<K, V> extends java.util.SortedMap<K, V>
     /**
      * Returns a reverse order <code>Set</code> view of the keys contained in this map. The set's iterator
      * returns the keys in descending order. The set is backed by the map, so changes to the map are reflected
-     * in the set, and vice-versa. If the map is modified while an iteration over the set is in progress
+     * in the set and vice versa.
+     * <p>
+     * Insertions cannot be made via the returned set and must be made on the main map.
+     * <p>
+     * <code>remove</code> and <code>fastRemove</code> on the returned set or on an iterator for the returned
+     * set are supported, but only if this map does not have an index; otherwise, attempts to remove an element
+     * raise <code>UnsupportedOperationException</code>.
+     * <p>
+     * If the map is modified while an iteration over the set is in progress
      * (except through the iterator's own <code>remove</code> or <code>fastRemove</code> operation), the results
      * of the iteration are undefined.
      *
@@ -122,8 +130,16 @@ public interface NavigableMap<K, V> extends java.util.SortedMap<K, V>
 
     /**
      * Returns a reverse order view of the mappings contained in this map.
-     * The descending map is backed by this map, so changes to the map are reflected in the descending map,
-     * and vice-versa. If either map is modified while an iteration over a collection view of either map is
+     * The descending map is backed by this map, so changes to the map are reflected in the descending map
+     * and vice versa.
+     *<p>
+     * Insertions cannot be made via the descending map and must be made on the main map.
+     * <p>
+     * <code>remove</code> and <code>fastRemove</code> on the descending map or on an iterator for the descending
+     * map are supported, but only if this map does not have an index; otherwise, attempts to remove an entry
+     * raise <code>UnsupportedOperationException</code>.
+     * <p>
+     * If either map is modified while an iteration over either map is
      * in progress (except through the iterator's own <code>remove</code> or <code>fastRemove</code>operation),
      * the results of the iteration are undefined. 
      *
@@ -134,8 +150,14 @@ public interface NavigableMap<K, V> extends java.util.SortedMap<K, V>
     /**
      * Returns a view of the portion of this map whose keys are strictly less than <code>toKey</code>, or less than
      * or equal to <code>toKey</code> if <code>inclusive</code> is true.
-     * The returned map is backed by this map, so changes in the returned map are reflected in this map,
-     * and vice-versa. The returned map supports all optional map operations that this map supports. 
+     * The returned map is backed by this map, so changes to this map are reflected in the returned map
+     * and vice versa.
+     *<p>
+     * Insertions cannot be made via the returned map and must be made on the main map.
+     * <p>
+     * <code>remove</code> and <code>fastRemove</code> on the returned map or on an iterator for the returned
+     * map are supported, but only if this map does not have an index; otherwise, attempts to remove an entry
+     * raise <code>UnsupportedOperationException</code>.
      * <p>
      * The returned map throws an <code>IllegalArgumentException</code> on an attempt to insert a key
      * outside its range.
@@ -151,8 +173,12 @@ public interface NavigableMap<K, V> extends java.util.SortedMap<K, V>
     /**
      * Returns a view of the portion of this map whose keys are strictly greater than <code>fromKey</code>, or greater
      * than or equal to <code>fromKey</code> if <code>inclusive</code> is true.
-     * The returned map is backed by this map, so changes in the returned map are reflected in this map,
-     * and vice-versa. The returned map supports all optional map operations that this map supports. 
+     *<p>
+     * Insertions cannot be made via the returned map and must be made on the main map.
+     * <p>
+     * <code>remove</code> and <code>fastRemove</code> on the returned map or on an iterator for the returned
+     * map are supported, but only if this map does not have an index; otherwise, attempts to remove an entry
+     * raise <code>UnsupportedOperationException</code>.
      * <p>
      * The returned map throws an <code>IllegalArgumentException</code> on an attempt to insert a key
      * outside its range.
@@ -169,11 +195,15 @@ public interface NavigableMap<K, V> extends java.util.SortedMap<K, V>
      * Returns a view of the portion of this map whose keys range from <code>fromKey</code> to <code>toKey</code>.
      * If <code>fromKey</code> and <code>toKey</code> are equal, the returned map is empty unless
      * <code>fromExclusive</code> and <code>toExclusive</code> are both <code>true</code>.
-     * The returned map is backed by this map, so changes in the returned map are reflected in this map, and
-     * vice-versa. The returned map supports all optional map operations that this map supports. 
+     *<p>
+     * Insertions cannot be made via the returned map and must be made on the main map.
+     * <p>
+     * <code>remove</code> and <code>fastRemove</code> on the returned map or on an iterator for the returned
+     * map are supported, but only if this map does not have an index; otherwise, attempts to remove an entry
+     * raise <code>UnsupportedOperationException</code>.
      * <p>
      * The returned map throws an <code>IllegalArgumentException</code> on an attempt to insert a key
-     * outside its range, or to construct a submap either of whose endpoints lie outside its range.
+     * outside its range.
      *
      * @param fromKey Low endpoint of the keys in the returned map.
      * @param fromInclusive <code>true</code> if the low endpoint is to be included in the returned view;
diff --git a/java/src/IceSSL/CertificateVerifier.java b/java/src/IceSSL/CertificateVerifier.java
index 9d2f971c09f..eae8cd936e5 100644
--- a/java/src/IceSSL/CertificateVerifier.java
+++ b/java/src/IceSSL/CertificateVerifier.java
@@ -9,15 +9,18 @@
 
 package IceSSL;
 
-//
-// An application can customize the certificate verification process
-// by implementing the CertificateVerifier interface.
-//
+/**
+ * An application can customize the certificate verification process
+ * by implementing the CertificateVerifier interface.
+ **/
 public interface CertificateVerifier
 {
-    //
-    // Return false if the connection should be rejected, or true to
-    // allow it.
-    // 
+    /**
+     * Determines whether a connection should be accepted or rejected.
+     *
+     * @param info The details of the connection.
+     * @return <code>true</code> if the connection should be accepted;
+     * <code>false</code>, otherwise.
+     **/
     boolean verify(ConnectionInfo info);
 }
diff --git a/java/src/IceSSL/ConnectionInfo.java b/java/src/IceSSL/ConnectionInfo.java
index 5e10a24bec8..7f086722200 100644
--- a/java/src/IceSSL/ConnectionInfo.java
+++ b/java/src/IceSSL/ConnectionInfo.java
@@ -9,44 +9,44 @@
 
 package IceSSL;
 
-//
-// ConnectionInfo contains information that may be of use to a
-// CertificateVerifier or an application that wants information
-// about its peer.
-//
+/**
+ * This class provides information about a connection to applications
+ * that require information about a peer, for example, to implement
+ * a CertificateVerifier.
+ *
+ * @see CertificateVerifier
+ **/
 public class ConnectionInfo
 {
-    //
-    // The certificate chain. This may be null if the peer did not
-    // supply a certificate. The peer's certificate (if any) is the
-    // first one in the chain.
-    //
+    /**
+     * The certificate chain. This may be null if the peer did not
+     * supply a certificate. The peer's certificate (if any) is the
+     * first one in the chain.
+     **/
     public java.security.cert.Certificate[] certs;
 
-    //
-    // The name of the negotiated cipher.
-    //
+    /**
+     * The name of the negotiated cipher.
+     **/
     public String cipher;
 
-    //
-    // The local TCP/IP host & port.
-    //
+    /**
+     * The local TCP/IP host & port.
+     **/
     public java.net.InetSocketAddress localAddr;
 
-    //
-    // The remote TCP/IP host & port.
-    //
+    /**
+     * The remote TCP/IP host & port.
+     **/
     public java.net.InetSocketAddress remoteAddr;
 
-    //
-    // If the connection is incoming this bool is true, false
-    // otherwise.
-    //
+    /**
+     * <code>true</code> if the connection is incoming; <code>false</code> otherwise.
+     **/
     public boolean incoming;
 
-    //
-    // The name of the object adapter that hosts this endpoint, if
-    // any.
-    //
+    /**
+     * The name of the object adapter that hosts this endpoint, if any.
+     **/
     public String adapterName;
 }
diff --git a/java/src/IceSSL/ConnectionInvalidException.java b/java/src/IceSSL/ConnectionInvalidException.java
index 35eab43b584..67751a6ea76 100644
--- a/java/src/IceSSL/ConnectionInvalidException.java
+++ b/java/src/IceSSL/ConnectionInvalidException.java
@@ -9,22 +9,41 @@
 
 package IceSSL;
 
+/**
+ * Indicates that a connection is not an SSL connection.
+ **/
 public final class ConnectionInvalidException extends Ice.LocalException
 {
+    /**
+     * Creates an instance with a <code>null</code> <code>reason</code> field.
+     **/
     public ConnectionInvalidException()
     {
     }
 
+    /**
+     * Creates an instance with the specified <code>reason</code>field.
+     *
+     * @param reason The reason why the connection is considered invalid.
+     **/
     public ConnectionInvalidException(String reason)
     {
         this.reason = reason;
     }
 
+    /**
+     * Returns the name of this exception.
+     *
+     * @return Returns <code>"Ice::ConnectionInvalidException"</code>.
+     **/
     public String
     ice_name()
     {
         return "Ice::ConnectionInvalidException";
     }
 
+    /**
+     * The reason why the connection is considered invalid.
+     **/
     public String reason;
 }
diff --git a/java/src/IceSSL/PasswordCallback.java b/java/src/IceSSL/PasswordCallback.java
index be1e9dff4cd..9fc76d6e59f 100644
--- a/java/src/IceSSL/PasswordCallback.java
+++ b/java/src/IceSSL/PasswordCallback.java
@@ -9,28 +9,37 @@
 
 package IceSSL;
 
-//
-// A password callback is an alternate way of supplying the plug-in with
-// passwords that avoids using plaintext configuration properties.
-//
+/**
+ * A password callback is an alternate way to supply the plug-in with
+ * passwords; this avoids using plain text configuration properties.
+ **/
 public interface PasswordCallback
 {
-    //
-    // Obtain the password for the key. If an alias was selected using
-    // the IceSSL.Alias property, the value of the property is provided.
-    // The return value must not be null.
-    //
+    /**
+     * Returns the password for the key. If an alias was selected
+     * by setting the <code>IceSSL.Alias</code> property, <code>alias</code>
+     * contains the property's value.
+     *
+     * @param alias The value of the property <code>IceSSL.Alias</code>, if that
+     * property is set; <code>null</code>, otherwise.
+     * @return The password for the key. The return value must not be <code>null</code>.
+     * 
+     **/
     char[] getPassword(String alias);
 
-    //
-    // Obtain the password for validating the truststore. Return null
-    // to skip truststore validation.
-    //
+    /**
+     * Returns the password for validating the truststore.
+     *
+     * @return The password. To skip truststore validation,
+     * return <code>null</code>.
+     **/
     char[] getTruststorePassword();
 
-    //
-    // Obtain the password for validating the keystore. Return null
-    // to skip keystore validation.
-    //
+    /**
+     * Returns the password for validating the keystore.
+     *
+     * @return The password. To skip keystore validation,
+     * return <code>null</code>.
+     **/
     char[] getKeystorePassword();
 }
diff --git a/java/src/IceSSL/Plugin.java b/java/src/IceSSL/Plugin.java
index 7e7aabf5651..bb6c1cbf7f8 100644
--- a/java/src/IceSSL/Plugin.java
+++ b/java/src/IceSSL/Plugin.java
@@ -9,66 +9,86 @@
 
 package IceSSL;
 
+/**
+ * Interface that allows applications to interact with the IceSSL plug-in.
+ **/
 public interface Plugin extends Ice.Plugin
 {
-    //
-    // Establish the SSL context. This must be done before the
-    // plug-in is initialized, therefore the application must define
-    // the property Ice.InitPlugins=0, set the context, and finally
-    // invoke initializePlugins on the PluginManager.
-    //
-    // When the application supplies its own SSL context, the
-    // plug-in skips its normal property-based configuration.
-    //
+    /**
+     * Establishes the SSL context. The context must be established before
+     * plug-in is initialized. Therefore, the application must set
+     * the property <code>Ice.InitPlugins</code> to zero, call
+     * <code>setContext</code> to set the context, and finally
+     * invoke <code>initializePlugins</code> on the <code>PluginManager</code>.
+     * <p>
+     * If an application supplies its own SSL context, the
+     * plug-in skips its normal property-based configuration.
+     *
+     * @param context The SSL context for the plug-in.
+     **/
     void setContext(javax.net.ssl.SSLContext context);
 
-    //
-    // Obtain the SSL context. Use caution when modifying this value.
-    // Changes made to this value have no effect on existing connections.
-    //
+    /**
+     * Returns the SSL context. Use caution when modifying the returned
+     * value: changes made to this value do not affect existing connections.
+     *
+     * @return The SSL context for the plug-in.
+     **/
     javax.net.ssl.SSLContext getContext();
 
-    //
-    // Establish the certificate verifier object. This should be
-    // done before any connections are established.
-    //
+    /**
+     * Establishes the certificate verifier. This must be
+     * done before any connections are established.
+     *
+     * @param verifier The certificate verifier.
+     **/
     void setCertificateVerifier(CertificateVerifier verifier);
 
-    //
-    // Obtain the certificate verifier object. Returns null if no
-    // verifier is set.
-    //
+    /**
+     * Returns the certificate verifier.
+     *
+     * @return The certificate verifier (<code>null</code> if not set).
+     **/
     CertificateVerifier getCertificateVerifier();
 
-    //
-    // Establish the password callback object. This should be
-    // done before the plug-in is initialized.
-    //
+    /**
+     * Establishes the password callback. This must be
+     * done before the plug-in is initialized.
+     *
+     * @param callback The password callback.
+     **/
     void setPasswordCallback(PasswordCallback callback);
 
-    //
-    // Obtain the password callback object. Returns null if no
-    // callback is set.
-    //
+    /**
+     * Returns the password callback.
+     *
+     * @return The password callback (<code>null</code> if not set).
+     **/
     PasswordCallback getPasswordCallback();
 
-    //
-    // Supplies an input stream for the keystore. Calling this method
-    // causes IceSSL to ignore the IceSSL.Keystore property.
-    //
+    /**
+     * Supplies an input stream for the keystore. Calling this method
+     * causes IceSSL to ignore the <code>IceSSL.Keystore</code> property.
+     *
+     * @param stream The input stream for the keystore.
+     **/
     void setKeystoreStream(java.io.InputStream stream);
 
-    //
-    // Supplies an input stream for the truststore. Calling this method
-    // causes IceSSL to ignore the IceSSL.Truststore property. It is
-    // legal to supply the same input stream as setKeystoreStream, in
-    // which case IceSSL uses the certificates contained in the keystore.
-    //
+    /**
+     * Supplies an input stream for the truststore. Calling this method
+     * causes IceSSL to ignore the <code>IceSSL.Truststore</code> property. It is
+     * legal to supply the same input stream as the one for <code>setKeystoreStream</code>,
+     * in which case IceSSL uses the certificates contained in the keystore.
+     *
+     * @param stream The input stream for the truststore.
+     **/
     void setTruststoreStream(java.io.InputStream stream);
 
-    //
-    // Add an input stream for the random number seed. You may call
-    // this method multiple times if necessary.
-    //
+    /**
+     * Adds an input stream for the random number seed. You may call
+     * this method multiple times if necessary.
+     *
+     * @param stream The input stream for the random number seed.
+     **/
     void addSeedStream(java.io.InputStream stream);
 }
diff --git a/java/src/IceSSL/PluginFactory.java b/java/src/IceSSL/PluginFactory.java
index fab146a9e6a..0e7fdf0c537 100644
--- a/java/src/IceSSL/PluginFactory.java
+++ b/java/src/IceSSL/PluginFactory.java
@@ -9,8 +9,22 @@
 
 package IceSSL;
 
+/**
+ * Plug-in factories must implement this interface.
+ **/
 public class PluginFactory implements Ice.PluginFactory
 {
+    /**
+     * Returns a new plug-in.
+     *
+     * @param communicator The communicator for the plug-in.
+     * @param name The name of the plug-in.
+     * @param args The arguments that are specified in the plug-in's configuration.
+     *
+     * @return The new plug-in. <code>null</code> can be returned to indicate
+     * that a general error occurred. Alterntively, <code>create</code> can throw
+     * <code>PluginInitializationException</code> to provide more detailed information.
+     **/
     public Ice.Plugin
     create(Ice.Communicator communicator, String name, String[] args)
     {