Lots of javadoc comments.

49 files changed, 2722 insertions, 113 deletions

diff --git a/java/src/Freeze/Map.java b/java/src/Freeze/Map.java
index 5769b1e2a79..debe0c16f57 100644
--- a/java/src/Freeze/Map.java
+++ b/java/src/Freeze/Map.java
@@ -9,39 +9,67 @@
 
 package Freeze;
 
+/**
+ * Interface for Freeze maps.
+ *
+ * @see Connection
+ **/
 public interface Map<K, V> extends NavigableMap<K, V>
 {
-    //
-    // Faster alternative to the standard put() method because it
-    // doesn't read and decode the old value.
-    //
+    /**
+     * Alternative to <code>java.util.SortedMap.put</code>. This version
+     * is more efficient because it does not decode and return the
+     * old value.
+     **/
     void fastPut(K key, V value);
 
+    /**
+     * Closes the database associated with this map, as well as all open iterators.
+     * A map must be closed when it is no longer needed, either directly, or by
+     * closing the <code>Connection</code> associated with this map.
+     **/
     void close();
 
-    //
-    // Close all iterators for this map. Returns the number of
-    // iterators that were closed.
-    //
+    /**
+     * Closes all iterators for this map.
+     *
+     * @return The number of iterators that were closed.
+     **/
     int closeAllIterators();
 
-    //
-    // Close this map and destroy the underlying Berkeley DB database.
-    //
+    /**
+     * Closes this map and destroys the underlying Berkeley DB database along with any indexes.
+     **/
     void destroy();
 
     /**
-     *
-     * The entry iterator allows clients to explicitly close the iterator
-     * and free resources allocated for the iterator as soon as possible.
-     *
+     * An <code>EntryIterator</code> allows the application to explicitly
+     * close an iterator and free resources allocated for the iterator
+     * in a timely fashion.
      **/
     public interface EntryIterator<T> extends java.util.Iterator<T>
     {
+        /**
+         * Closes this iterator, reclaiming associated resources.
+         **/
         void close();
-        void destroy(); // an alias for close
+
+        /**
+         * Closes this iterator, reclaiming associated resources. This
+         * method is an alias for <code>close</code>.
+         **/
+        void destroy();
     }
 
+    /**
+     * Returns the connection associated with this map.
+     *
+     * @return The connection associated with this map.
+     **/
     Connection getConnection();
+
+    /**
+     * Closes the database for this map.
+     **/
     void closeDb();
 }
diff --git a/java/src/Freeze/NavigableMap.java b/java/src/Freeze/NavigableMap.java
index 7d9e3ecfbc8..42e8960453d 100644
--- a/java/src/Freeze/NavigableMap.java
+++ b/java/src/Freeze/NavigableMap.java
@@ -9,34 +9,195 @@
 
 package Freeze;
 
+/**
+ * Parent interface for Freeze maps.
+ **/
 public interface NavigableMap<K, V> extends java.util.SortedMap<K, V>
 {
-    //
-    // Faster alternative to the standard remove() method because it
-    // doesn't read and decode the old value.
-    //
+    /**
+     * Alternative to <code>java.util.SortedMap.remove</code>. This version
+     * is more efficient because it does not decode and return the
+     * old value.
+     *
+     * @param key The key of the entry to remove.
+     * @return <code>true</code> if an entry for <code>key</code> was removed;
+     * <code>false</code>, otherwise.
+     **/
     boolean fastRemove(K key);
 
+    /**
+     * Returns The entry with the least key.
+     *
+     * @return The entry with the least key, or <code>null</code> if the map is empty.
+     **/
     java.util.Map.Entry<K, V> firstEntry();
+
+    /**
+     * Returns The entry with the greatest key.
+     *
+     * @return The entry with the greatest key, or <code>null</code> if the map is empty.
+     **/
     java.util.Map.Entry<K, V> lastEntry();
 
+    /**
+     * Returns the entry with the least key greater than or equal to the given key.
+     *
+     * @param key The key.
+     * @return The entry with the least key greater than or equal to the given key,
+     * or <code>null</code> if there is no such entry.
+     **/
     java.util.Map.Entry<K, V> ceilingEntry(K key);
+
+    /**
+     * Returns the entry with the greatest key less than or equal to the given key.
+     *
+     * @param key The key.
+     * @return The entry with the greatest key less than or equal to the given key,
+     * or <code>null</code> if there is no such entry.
+     **/
     java.util.Map.Entry<K, V> floorEntry(K key);
+
+    /**
+     * Returns the entry with the least key strictly greater than the given key.
+     *
+     * @param key The key.
+     * @return The entry with the least key strictly greater than the given key,
+     * or <code>null</code> if there is no such entry.
+     **/
     java.util.Map.Entry<K, V> higherEntry(K key);
+
+    /**
+     * Returns the entry with the greatest key strictly less than the given key.
+     *
+     * @param key The key.
+     * @return The entry with the greatest key strictly less than the given key,
+     * or <code>null</code> if there is no such entry.
+     **/
     java.util.Map.Entry<K, V> lowerEntry(K key);
 
+    /**
+     * Returns the least key greater than or equal to the given key.
+     *
+     * @param key The key.
+     * @return The least key greater than or equal to the given key,
+     * or <code>null</code> if there is no such key.
+     **/
     K ceilingKey(K key);
+
+    /**
+     * Returns the greatest key less than or equal to the given key.
+     *
+     * @param key The key.
+     * @return The greatest key less than or equal to the given key,
+     * or <code>null</code> if there is no such key.
+     **/
     K floorKey(K key);
+
+    /**
+     * Returns the least key strictly greater than the given key.
+     *
+     * @return The least key strictly greater than the given key,
+     * or <code>null</code> if there is no such key.
+     **/
     K higherKey(K key);
+
+    /**
+     * Returns the greatest key strictly less than the given key.
+     *
+     * @return The greatest key strictly less than the given key,
+     * or <code>null</code> if there is no such key.
+     **/
     K lowerKey(K key);
 
+    /**
+     * 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
+     * (except through the iterator's own <code>remove</code> or <code>fastRemove</code> operation), the results
+     * of the iteration are undefined.
+     *
+     * @return A reverse order set view of the keys in this map.
+     **/
     java.util.Set<K> descendingKeySet();
+
+    /**
+     * 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
+     * in progress (except through the iterator's own <code>remove</code> or <code>fastRemove</code>operation),
+     * the results of the iteration are undefined. 
+     *
+     * @return a Reverse order view of this map.
+     **/
     NavigableMap<K, V> descendingMap();
 
+    /**
+     * 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. 
+     * <p>
+     * The returned map throws an <code>IllegalArgumentException</code> on an attempt to insert a key
+     * outside its range.
+     *
+     * @param toKey High endpoint of the keys in the returned map.
+     * @param inclusive If <code>true</code>, the endpoint is included in the returned map; otherwise, the endpoint
+     * is excluded.
+     * @return 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.
+     **/
     NavigableMap<K, V> headMap(K toKey, boolean inclusive);
-    NavigableMap<K, V> subMap(K fromKey, boolean fromInclusive, K toKey, boolean toInclusive);
+
+    /**
+     * 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>
+     * The returned map throws an <code>IllegalArgumentException</code> on an attempt to insert a key
+     * outside its range.
+     *
+     * @param fromKey Low endpoint of the keys in the returned map.
+     * @param inclusive If <code>true</code>, the endpoint is included in the returned map; otherwise, the endpoint
+     * is excluded.
+     * @return 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.
+     **/
     NavigableMap<K, V> tailMap(K fromKey, boolean inclusive);
 
+    /**
+     * 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>
+     * 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.
+     *
+     * @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;
+     * <code>false, otherwise</code>.
+     * @param toKey High endpoint of the keys in the returned map.
+     * @param toInclusive <code>true</code> if the high endpoint is to be included in the returned view;
+     * <code>false, otherwise</code>.
+     * @return A view of the portion of this map whose keys range from <code>fromKey</code> to <code>toKey</code>.
+     **/
+    NavigableMap<K, V> subMap(K fromKey, boolean fromInclusive, K toKey, boolean toInclusive);
+
+    /**
+     * Removes and returns a key-value mapping associated with the least key in this map,
+     * or <code>null</code> if the map is empty.
+     *
+     * @return The removed first entry, or <code>null</code> if this map is empty.
+     **/
     java.util.Map.Entry<K, V> pollFirstEntry();
+
+    /**
+     * Removes and returns a key-value mapping associated with the greatest key in this map,
+     * or <code>null</code> if the map is empty.
+     *
+     * @return The removed last entry, or <code>null</code> if this map is empty.
+     **/
     java.util.Map.Entry<K, V> pollLastEntry();
 }
diff --git a/java/src/Ice/AMD_Object_ice_invoke.java b/java/src/Ice/AMD_Object_ice_invoke.java
index 43a0edc9765..8a7d9733c99 100644
--- a/java/src/Ice/AMD_Object_ice_invoke.java
+++ b/java/src/Ice/AMD_Object_ice_invoke.java
@@ -9,8 +9,33 @@
 
 package Ice;
 
+/**
+ * Callback interface for <Blobject> AMD servants.
+ *
+ @see BlobjectAsync
+ **/
 public interface AMD_Object_ice_invoke
 {
+    /**
+     * Indicates to the Ice run time that an operation
+     * completed.
+     *
+     * @param ok <code>true</code> indicates that the operation
+     * completed successfully; <code>false</code> indicates that the
+     * operation raised user exception.
+     * @param outParams The encoded out-parameters for the operation or,
+     * if <code>ok</code> is <code>false</code>, the encoded user exception.
+     **/
     void ice_response(boolean ok, byte[] outParams);
+
+    /**
+     * Indicates to the Ice run time that an operation completed
+     * with a run-time exception.
+     *
+     * @param ex The encoded Ice run-time exception. Note that, if <code>ex</code>
+     * is a user exception, the caller receives <code>UnknownUserException</code>.
+     * Use <code>ice_response</code> to raise user exceptions.
+     **/
+
     void ice_exception(java.lang.Exception ex);
 }
diff --git a/java/src/Ice/AMISentCallback.java b/java/src/Ice/AMISentCallback.java
index 2aca793f7f8..659b5be65e9 100644
--- a/java/src/Ice/AMISentCallback.java
+++ b/java/src/Ice/AMISentCallback.java
@@ -9,7 +9,23 @@
 
 package Ice;
 
+/**
+ * Callback interface for AMI invocations. This is useful
+ * for applications that send asynchronous invocations that
+ * might not be sent for some time and, therefore, are
+ * queued in the Ice run time for transmission.
+ * <p>
+ * The Ice run time calls <code>ice_sent</code> if an
+ * an AMI invocation cannot be written to transport and was
+ * queued for later transmission. Applications that need to
+ * implement flow control for AMI invocations can implement
+ * this interface on the corresponding AMI callback object.
+ **/
 public interface AMISentCallback
 {
+    /**
+     * Indicates to the caller of an AMI operation that
+     * the invocation was queued for later transmission.
+     **/
     void ice_sent();
 };
diff --git a/java/src/Ice/AMI_Object_ice_flushBatchRequests.java b/java/src/Ice/AMI_Object_ice_flushBatchRequests.java
index 4f488466a69..36124db03b0 100644
--- a/java/src/Ice/AMI_Object_ice_flushBatchRequests.java
+++ b/java/src/Ice/AMI_Object_ice_flushBatchRequests.java
@@ -9,8 +9,19 @@
 
 package Ice;
 
+/**
+ * Callback object for <code>ObjectPrx.ice_flushBatchRequests_async</code>.
+ **/
 public abstract class AMI_Object_ice_flushBatchRequests extends IceInternal.BatchOutgoingAsync
 {
+    /**
+     * Indicates to the caller that a call to <code>ice_flushBatchRequests_async</code>
+     * raised an Ice run-time exception.
+     *
+     * @param ex The run-time exception that was raised.
+     *
+     * @see ObjectPrx.ice_flushBatchRequests_async
+     **/
     public abstract void ice_exception(LocalException ex);
 
     public final boolean __invoke(Ice.ObjectPrx prx)
diff --git a/java/src/Ice/AMI_Object_ice_invoke.java b/java/src/Ice/AMI_Object_ice_invoke.java
index aac15bd6b2d..a7235328900 100644
--- a/java/src/Ice/AMI_Object_ice_invoke.java
+++ b/java/src/Ice/AMI_Object_ice_invoke.java
@@ -9,9 +9,31 @@
 
 package Ice;
 
+/**
+ * Callback object for <code>Blobject</code> AMI invocations.
+ *
+ * @see Blobject
+ **/
 public abstract class AMI_Object_ice_invoke extends IceInternal.OutgoingAsync
 {
+    /**
+     * The Ice run time calls <code>ice_response</code> when an asynchronous operation invocation
+     * completes successfully or raises a user exception.
+     *
+     * @param ok Indicates the result of the invocation. If <code>true</code>, the operation
+     * completed succesfully; if <code>false</code>, the operation raised a user exception.
+     * @param outParams Contains the encoded out-parameters of the operation (if any) if <code>ok</code>
+     * is <code>true</code>; otherwise, if <code>ok</code> is <code>false</code>, contains the
+     * encoded user exception raised by the operation.
+     **/
     public abstract void ice_response(boolean ok, byte[] outParams);
+
+    /**
+     * The Ice run time calls <code>ice_exception</code> when an asynchronous operation invocation
+     * raises an Ice run-time exception.
+     *
+     * @param ex The encoded Ice run-time exception raised by the operation.
+     **/
     public abstract void ice_exception(LocalException ex);
 
     public final boolean __invoke(Ice.ObjectPrx prx, String operation, OperationMode mode,
diff --git a/java/src/Ice/Application.java b/java/src/Ice/Application.java
index 7b112078417..753e38400f9 100644
--- a/java/src/Ice/Application.java
+++ b/java/src/Ice/Application.java
@@ -9,40 +9,111 @@
 
 package Ice;
 
+/**
+ * Utility base class that makes it easy to to correctly initialize and finalize
+ * the Ice run time, as well as handle signals. Unless the application specifies
+ * a logger, <Application> installs a per-process logger that logs to the standard
+ * error output.
+ * <p>
+ * Applications must create a derived class that implements the <code>run</code> method.
+ * <p>
+ * A program can contain only one instance of this class.
+ *
+ * @see run
+ * @see Communicator
+ * @see Logger
+ **/
 public abstract class Application
 {
-
+    /**
+     * Initializes an instance that calls <code>Communicator.shutdown</code> if
+     * a signal is received.
+     **/
     public
     Application()
     {
     }
 
+    /**
+     * Initializes an instance that handles signals according to the signal
+     * policy.
+     *
+     * @param signalPolicy Determines how to respond to signals.
+     *
+     * @see SignalPolicy
+     **/
     public
     Application(SignalPolicy signalPolicy)
     {
         _signalPolicy = signalPolicy;
     }
 
-    //
-    // This main() must be called by the global main(). main()
-    // initializes the Communicator, calls run(), and destroys
-    // the Communicator upon return from run(). It thereby handles
-    // all exceptions properly, i.e., error messages are printed
-    // if exceptions propagate to main(), and the Communicator is
-    // always destroyed, regardless of exceptions.
-    //
+    /**
+     * The application must call <code>main</code> after it has
+     * instantiated the derived class. <code>main</code> creates
+     * a communicator, establishes the specified signal policy, and,
+     * once <code>run</code> returns, destroys the communicator.
+     * <p>
+     * The method prints an error message for any exception that propagates
+     * out of <code>run</code> and ensures that the communicator is
+     * destroyed correctly even if <code>run</code> completes abnormally.
+     *
+     * @param appName The name of the application. This parameter is used to initialize
+     * the value of the <code>Ice.ProgramName</code> property.
+     * @param args The arguments for the application (as passed to <code>Main(String[])</code>
+     * by the operating system.
+     * @return The value returned by <code>run</code>. If <code>run</code> terminates with an exception,
+     * the return value is non-zero.
+     **/
     public final int
     main(String appName, String[] args)
     {
         return mainInternal(appName, args, new InitializationData(), null);
     }
 
+    /**
+     * The application must call <code>main</code> after it has
+     * instantiated the derived class. <code>main</code> creates
+     * a communicator, establishes the specified signal policy, and,
+     * once <code>run</code> returns, destroys the communicator.
+     * <p>
+     * The method prints an error message for any exception that propagates
+     * out of <code>run</code> and ensures that the communicator is
+     * destroyed correctly even if <code>run</code> completes abnormally.
+     *
+     * @param appName The name of the application. This parameter is used to initialize
+     * the value of the <code>Ice.ProgramName</code> property.
+     * @param configFile The configuration file with which to initialize
+     * Ice properties.
+     * @return The value returned by <code>run</code>. If <code>run</code> terminates with an exception,
+     * the return value is non-zero.
+     **/
     public final int
     main(String appName, String[] args, String configFile)
     {
         return main(appName, args, configFile, null);
     }
 
+    /**
+     * The application must call <code>main</code> after it has
+     * instantiated the derived class. <code>main</code> creates
+     * a communicator, establishes the specified signal policy, and,
+     * once <code>run</code> returns, destroys the communicator.
+     * <p>
+     * The method prints an error message for any exception that propagates
+     * out of <code>run</code> and ensures that the communicator is
+     * destroyed correctly even if <code>run</code> completes abnormally.
+     *
+     * @param appName The name of the application. This parameter is used to initialize
+     * the value of the <code>Ice.ProgramName</code> property.
+     * @param args The arguments for the application (as passed to <code>Main(String[])</code>.
+     * @param configFile The configuration file with which to initialize Ice properties.
+     * @param overrideProps Property values that override any settings in <code>configFile</code.
+     * @return The value returned by <code>run</code>. If <code>run</code> terminates with an exception,
+     * the return value is non-zero.
+     *
+     * @see Properties
+     **/
     public final int
     main(String appName, String[] args, String configFile, Properties overrideProps)
     {
@@ -68,38 +139,81 @@ public abstract class Application
         return mainInternal(appName, args, initData, overrideProps);
     }
 
+    /**
+     * The application must call <code>main</code> after it has
+     * instantiated the derived class. <code>main</code> creates
+     * a communicator, establishes the specified signal policy, and,
+     * once <code>run</code> returns, destroys the communicator.
+     * <p>
+     * The method prints an error message for any exception that propagates
+     * out of <code>run</code> and ensures that the communicator is
+     * destroyed correctly even if <code>run</code> completes abnormally.
+     *
+     * @param appName The name of the application. This parameter is used to initialize
+     * the value of the <code>Ice.ProgramName</code> property.
+     * @param args The arguments for the application (as passed to <code>Main(String[])</code>.
+     * @param initializationData Additional data used to initialize the communicator.
+     * @return The value returned by <code>run</code>. If <code>run</code> terminates with an exception,
+     * the return value is non-zero.
+     *
+     * @see InitializationData
+     **/
     public final int
     main(String appName, String[] args, InitializationData initializationData)
     {
         return mainInternal(appName, args, initializationData, null);
     }
 
+    /**
+     * Called once the communicator has been initialized. The derived class must
+     * implement <code>run</code>, which is the application's starting method.
+     *
+     * @param args The argument vector for the application. <code>Application</code>
+     * scans the argument vector passed to <code>main</code> for options that are
+     * specific to the Ice run time and removes them; therefore, the vector passed
+     * to <code>run</code> is free from Ice-related options and contains only options
+     * and arguments that are application-specific.
+     *
+     * @param args The argument vector for the application, minus any Ice-specific options.
+     * @return The <code>run</code> method should return zero for successful termination, and
+     * non-zero otherwise. <code>Application.main</code> returns the value returned by <code>run</code>.
+     **/
     public abstract int
     run(String[] args);
 
-    //
-    // Return the application name, i.e., argv[0].
-    //
+    /**
+     * Returns the value of <code>appName</code> that is passed to <code>main</code> (which is also the
+     * the value of <code>Ice.ProgramName</code>). This method is useful mainly for error messages that
+     * include the application name. Because <appName> is a static method, it is available from anywhere
+     * in the program.
+     *
+     * @return The name of the application.
+     **/
     public static String
     appName()
     {
         return _appName;
     }
 
-    //
-    // One limitation of this class is that there can only be one
-    // Application instance, with one global Communicator, accessible
-    // with this communicator() operation. This limitiation is due to
-    // how the signal handling functions below operate. If you require
-    // multiple Communicators, then you cannot use this Application
-    // framework class.
-    //
+    /**
+     * Returns the communicator for the application. Because <communicator> is a static method,
+     * it permits access to the communicator from anywhere in the program. Note that, as a consequence,
+     * you cannot  more than one instance of <code>Application</code> in a program.
+     *
+     * @return The communicator for the application.
+     **/
     public static Communicator
     communicator()
     {
         return _communicator;
     }
 
+    /**
+     * Instructs <code>Application</code> to call <code>Communicator.destroy</code> on receipt of a signal.
+     * This is default signal handling policy established by the default constructor.
+     *
+     * @see Communicator.destroy
+     **/
     public static void
     destroyOnInterrupt()
     {
@@ -132,6 +246,11 @@ public abstract class Application
         }
     }
     
+    /**
+     * Instructs <code>Application</code> to call <code>Communicator.shutdown</code> on receipt of a signal.
+     *
+     * @see Communicator.shutdown
+     **/
     public static void
     shutdownOnInterrupt()
     {
@@ -164,15 +283,17 @@ public abstract class Application
         }
     }
 
-    //
-    // Install a custom shutdown hook. This hook is registered as a
-    // shutdown hook and should do whatever is necessary to terminate
-    // the application. Note that this runs as a shutdown hook so the
-    // code must obey the same rules as a shutdown hook (specifically
-    // don't call exit!). The shutdown and destroy shutdown interrupts
-    // are cleared. This hook is automatically unregistered after
-    // Application.run() returns.
-    //
+    /**
+     * Installs a custom shutdown hook. The implementation of the shutdown
+     * hook can do whatever cleanup is necessary to shut down the application.
+     * The hook is unregistered once <code>run</code> returns.
+     * Note that the hook must obey the rules for shutdown hooks; specifically,
+     * it must not call <code>exit</code>.
+     *
+     * @param newHook The thread to run on shutdown.
+     *
+     * @see java.lang.Runtime.addShutdownHook
+     **/
     public static void
     setInterruptHook(java.lang.Thread newHook) // Pun intended.
     {
@@ -194,9 +315,10 @@ public abstract class Application
         }
     }
     
-    //
-    // This clears any shutdown hooks including any custom hook.
-    //
+    /**
+     * Clears any shutdownn hooks, including any hook established with <code>destroyOnInterrupt</code> or
+     * <code>shutdownOnInterrupt</code>.
+     **/
     public static void
     defaultInterrupt()
     {
@@ -211,6 +333,12 @@ public abstract class Application
         }
     }
 
+    /**
+     * Determines whether the application shut down intentionally or was forced to shut down by the JVM. This
+     * is useful for logging purposes.
+     *
+     * @return <code>true</code> if a shutdown hook caused the communicator to shut down; false otherwise.
+     **/
     public static boolean
     interrupted()
     {
diff --git a/java/src/Ice/ArrayListHolder.java b/java/src/Ice/ArrayListHolder.java
index 1a28bcae6b4..23464403aae 100644
--- a/java/src/Ice/ArrayListHolder.java
+++ b/java/src/Ice/ArrayListHolder.java
@@ -9,18 +9,32 @@
 
 package Ice;
 
+/**
+ * Holder class for array lists that are in- or inout-parameters.
+ **/
 public final class ArrayListHolder
 {
+    /**
+     * Instantiates the class with a <code>null</code> <code>ArrayList</code>.
+     **/
     public
     ArrayListHolder()
     {
     }
 
+    /**
+     * Instantiates the class with the passed <code>ArrayList</code>.
+     *
+     * @param value The <code>ArrayList</code> stored by this holder.
+     **/
     public
     ArrayListHolder(java.util.ArrayList value)
     {
         this.value = value;
     }
 
+    /**
+     * The <code>ArrayList</code> stored by this holder.
+     **/
     public java.util.ArrayList value;
 }
diff --git a/java/src/Ice/Blobject.java b/java/src/Ice/Blobject.java
index 67ac51fc6dc..61f739baa4c 100644
--- a/java/src/Ice/Blobject.java
+++ b/java/src/Ice/Blobject.java
@@ -9,9 +9,25 @@
 
 package Ice;
 
+/**
+ * Base class for dynamic dispatch servants. A server application
+ * derives a concrete servant class from <code>Blobject</code. that
+ * implements the <code>ice_invoke</code> method.
+ **/
 public abstract class Blobject extends Ice.ObjectImpl
 {
-    // Returns true if ok, false if user exception.
+    /**
+     * Dispatch an incoming request.
+     *
+     * @param inParams The encoded in-parameters for the operation.
+     * @param outParams The encoded out-paramaters and return value
+     * for the operation. The return value follows any out-parameters.
+     * @return If the operation completed successfully, the return value
+     * is <code>true</code>. If the operation raises a user exception,
+     * the return value is <code>false</code>; in this case, <code>outParams</code>
+     * must contain the encoded user exception. If the operation raises an
+     * Ice run-time exception, it must throw it directly.
+     **/
     public abstract boolean
     ice_invoke(byte[] inParams, ByteSeqHolder outParams, Current current);
 
diff --git a/java/src/Ice/BooleanHolder.java b/java/src/Ice/BooleanHolder.java
index 5dabc667b4d..4c7e069858d 100644
--- a/java/src/Ice/BooleanHolder.java
+++ b/java/src/Ice/BooleanHolder.java
@@ -9,18 +9,32 @@
 
 package Ice;
 
+/**
+ * Holder class for booleans that are in- or inout-parameters.
+ **/
 public final class BooleanHolder
 {
+    /**
+     * Instantiates the class with the value <code>false</code>.
+     **/
     public
     BooleanHolder()
     {
     }
 
+    /**
+     * Instantiates the class with the passed value.
+     *
+     * @param value The <code>boolean</code> value stored by this holder.
+     **/
     public
     BooleanHolder(boolean value)
     {
         this.value = value;
     }
 
+    /**
+     * The <code>boolean</code> value stored by this holder.
+     **/
     public boolean value;
 }
diff --git a/java/src/Ice/ByteHolder.java b/java/src/Ice/ByteHolder.java
index 20d71cf2964..0c634070a11 100644
--- a/java/src/Ice/ByteHolder.java
+++ b/java/src/Ice/ByteHolder.java
@@ -9,18 +9,32 @@
 
 package Ice;
 
+/**
+ * Holder class for bytes that are in- or inout-parameters.
+ **/
 public final class ByteHolder
 {
+    /**
+     * Instantiates the class with the value zero.
+     **/
     public
     ByteHolder()
     {
     }
 
+    /**
+     * Instantiates the class with the passed value.
+     *
+     * @param value The <code>byte</code> value stored by this holder.
+     **/
     public
     ByteHolder(byte value)
     {
         this.value = value;
     }
 
+    /**
+     * The <code>byte</code> value stored by this holder.
+     **/
     public byte value;
 }
diff --git a/java/src/Ice/DispatchInterceptor.java b/java/src/Ice/DispatchInterceptor.java
index 5889d1b2977..4901aef9ab2 100644
--- a/java/src/Ice/DispatchInterceptor.java
+++ b/java/src/Ice/DispatchInterceptor.java
@@ -9,8 +9,29 @@
 
 package Ice;
 
+/**
+ * Base class that allows a server intercept incoming requests.
+ * The application must derive a concrete class from <code>DispatchInterceptor</code>
+ * that implements the <code>dispatch</code> operation. An instance of this derived
+ * class can be registered with an object adapter like any other servant.
+ * <p>
+ * A dispatch interceptor is useful particularly to automatically retry requests
+ * that have failed due to a recoverable error condition.
+ **/
 public abstract class DispatchInterceptor extends ObjectImpl
 {
+    /**
+     * Called by the Ice run time to dispatch an incoming request. The implementation
+     * of <code>dispatch</code> must dispatch the request to the actual servant.
+     *
+     * @param request The details of the incoming request.
+     * @return For synchronous dispatch, the return value must be whatever is
+     * returned <code>ice_dispatch</code>. For asynchronous dispatch, the return
+     * value must be <code>DispatchAsync</code>.
+     *
+     * @see Request
+     * @see DispatchStatus
+     **/
     public abstract DispatchStatus
     dispatch(Request request);
    
diff --git a/java/src/Ice/DispatchStatus.java b/java/src/Ice/DispatchStatus.java
index 7953b8c11e3..73d3e869173 100644
--- a/java/src/Ice/DispatchStatus.java
+++ b/java/src/Ice/DispatchStatus.java
@@ -9,23 +9,43 @@
 
 package Ice;
 
+/**
+ * Indicates the status of operation dispatch.
+ *
+ * @see DispatchInterceptor
+ **/
 public final class DispatchStatus
 {
     private static DispatchStatus[] __values = new DispatchStatus[3];
     private int __value;
 
     public static final int _DispatchOK = 0;
+
+    /**
+     * Indicates that an operation was dispatched synchronously and successfully.
+     **/
     public static final DispatchStatus DispatchOK =
         new DispatchStatus(_DispatchOK);
 
     public static final int _DispatchUserException = 1;
+
+    /**
+     * Indicates that an operation was dispatched synchronously and raised a user exception.
+     **/
     public static final DispatchStatus DispatchUserException =
         new DispatchStatus(_DispatchUserException);
 
     public static final int _DispatchAsync = 2;
+
+    /**
+     * Indicates that an operation was dispatched asynchronously.
+     **/
     public static final DispatchStatus DispatchAsync =
         new DispatchStatus(_DispatchAsync);
 
+    /**
+     * Converts an ordinal value to the corresponding enumerator.
+     **/
     public static DispatchStatus
     convert(int val)
     {
@@ -33,6 +53,9 @@ public final class DispatchStatus
         return __values[val];
     }
 
+    /**
+     * Returns the ordinal value of the current enumerator.
+     **/
     public int
     value()
     {
diff --git a/java/src/Ice/DoubleHolder.java b/java/src/Ice/DoubleHolder.java
index b9eccc5eeb9..aacf1fc0110 100644
--- a/java/src/Ice/DoubleHolder.java
+++ b/java/src/Ice/DoubleHolder.java
@@ -10,17 +10,31 @@
 package Ice;
 
 public final class DoubleHolder
+/**
+ * Holder class for doubles that are in- or inout-parameters.
+ **/
 {
+    /**
+     * Instantiates the class with the value zero.
+     **/
     public
     DoubleHolder()
     {
     }
 
+    /**
+     * Instantiates the class with the passed value.
+     *
+     * @param value The <code>double</code> value stored by this holder.
+     **/
     public
     DoubleHolder(double value)
     {
         this.value = value;
     }
 
+    /**
+     * The <code>double</code> value stored by this holder.
+     **/
     public double value;
 }
diff --git a/java/src/Ice/FloatHolder.java b/java/src/Ice/FloatHolder.java
index db8664c680a..74833551448 100644
--- a/java/src/Ice/FloatHolder.java
+++ b/java/src/Ice/FloatHolder.java
@@ -9,18 +9,32 @@
 
 package Ice;
 
+/**
+ * Holder class for floats that are in- or inout-parameters.
+ **/
 public final class FloatHolder
 {
+    /**
+     * Instantiates the class with the value zero.
+     **/
     public
     FloatHolder()
     {
     }
 
+    /**
+     * Instantiates the class with the passed value.
+     *
+     * @param value The <code>float</code> value stored by this holder.
+     **/
     public
     FloatHolder(float value)
     {
         this.value = value;
     }
 
+    /**
+     * The <code>float</code> value stored by this holder.
+     **/
     public float value;
 }
diff --git a/java/src/Ice/Holder.java b/java/src/Ice/Holder.java
index bdd4cd86811..2c5d75bab7c 100644
--- a/java/src/Ice/Holder.java
+++ b/java/src/Ice/Holder.java
@@ -9,18 +9,32 @@
 
 package Ice;
 
+/**
+ * Generic holder class for values that are in- or in-out parameters.
+ **/
 public final class Holder<T>
 {
+    /**
+     * Instantiates the class with the default-initialized value of type <code>T</code>.
+     **/
     public
     Holder()
     {
     }
 
+    /**
+     * Instantiates the class with the passed value.
+     *
+     * @param value The value stored by this holder.
+     **/
     public
     Holder(T value)
     {
         this.value = value;
     }
 
+    /**
+     * The <code>T</code> value stored by this holder.
+     **/
     public T value;
 }
diff --git a/java/src/Ice/InitializationData.java b/java/src/Ice/InitializationData.java
index 7f5f62822ae..466174af2bc 100644
--- a/java/src/Ice/InitializationData.java
+++ b/java/src/Ice/InitializationData.java
@@ -9,13 +9,28 @@
 
 package Ice;
 
+/**
+ * A class that encapsulates data to initialize a communicator.
+ *
+ * @see Communicator.intialize
+ * @see Properties
+ * @see Logger
+ * @see Stats
+ * @see ThreadNotification
+ **/
 public final class InitializationData implements Cloneable
 {
+    /**
+     * Creates an instance with all members set to <code>null</code>.
+     **/
     public
     InitializationData()
     {
     }
 
+    /**
+     * Creates and returns a copy of this object.
+     **/
     public java.lang.Object
     clone()
     {
@@ -33,8 +48,23 @@ public final class InitializationData implements Cloneable
         return o;
     }
 
+    /**
+     * The properties for the communicator.
+     **/
     public Properties properties;
+
+    /**
+     * The logger for the communicator.
+     **/
     public Logger logger;
+
+    /**
+     * The <Stats> instance for the communicator.
+     **/
     public Stats stats;
+
+    /**
+     * The thread hook for the communicator.
+     **/
     public ThreadNotification threadHook;
 }
diff --git a/java/src/Ice/InputStream.java b/java/src/Ice/InputStream.java
index 091fb9b8492..b3d6d13637f 100644
--- a/java/src/Ice/InputStream.java
+++ b/java/src/Ice/InputStream.java
@@ -9,65 +9,268 @@
 
 package Ice;
 
+/**
+ * Interface for input streams used to extract Slice types from a sequence
+ * of bytes.
+ *
+ * see OutputStream.
+ **/
 public interface InputStream
 {
+    /**
+     * Returns the communicator for this input stream.
+     *
+     * @return The communicator.
+     **/
     Communicator communicator();
 
+    /**
+     * Determines the behavior of the stream when extract Slice objects.
+     * A Slice object is "sliced" when a factory cannot be found for a Slice type ID.
+     *
+     * @param If <code>true</code> (the default), slicing is enabled; if <code>false</code>,
+     * slicing is disabled. If slicing is disabled and the stream encounters a Slice type ID
+     * during decoding for which no object factory is installed, it raises <code>NoObjectFactoryException</code>.
+     **/
     void sliceObjects(boolean slice);
 
+    /**
+     * Extracts a boolean value from the stream.
+     *
+     * @return The extracted boolean.
+     **/
     boolean readBool();
+
+    /**
+     * Extracts a sequence of boolean values from the stream.
+     *
+     * @return The extracted boolean sequence.
+     **/
     boolean[] readBoolSeq();
 
+    /**
+     * Extracts a byte value from the stream.
+     *
+     * @return The extracted byte.
+     **/
     byte readByte();
+    
+    /**
+     * Extracts a sequence of byte values from the stream.
+     *
+     * @return The extracted byte sequence.
+     **/
     byte[] readByteSeq();
 
+    /**
+     * Extracts a serializable Java object from the stream.
+     *
+     * @return The deserialized Java object.
+     **/
     java.io.Serializable readSerializable();
 
+    /**
+     * Extracts a short value from the stream.
+     *
+     * @return The extracted short value.
+     **/
     short readShort();
+
+    /**
+     * Extracts a sequence of short values from the stream.
+     *
+     * @return The extracted short sequence.
+     **/
     short[] readShortSeq();
 
+    /**
+     * Extracts an integer value from the stream.
+     *
+     * @return The extracted integer.
+     **/
     int readInt();
+
+    /**
+     * Extracts an integer value from the stream.
+     *
+     * @return The extracted integer sequence.
+     **/
     int[] readIntSeq();
 
+    /**
+     * Extracts a long value from the stream.
+     *
+     * @return The extracted long value.
+     **/
     long readLong();
+
+    /**
+     * Extracts a long sequence from the stream.
+     *
+     * @return The extracted long sequence.
+     **/
     long[] readLongSeq();
 
+    /**
+     * Extracts a float value from the stream.
+     *
+     * @return The extracted float value.
+     **/
     float readFloat();
+
+    /**
+     * Extracts a float sequence from the stream.
+     *
+     * @return The extracted float sequence.
+     **/
     float[] readFloatSeq();
 
+    /**
+     * Extracts a double value from the stream.
+     *
+     * @return The extracted double value.
+     **/
     double readDouble();
+
+    /**
+     * Extracts a double sequence from the stream.
+     *
+     * @return The extracted float sequence.
+     **/
     double[] readDoubleSeq();
 
+    /**
+     * Extracts a string from the stream.
+     *
+     * @return The extracted string.
+     **/
     String readString();
+
+    /**
+     * Extracts a string sequence from the stream.
+     *
+     * @return The extracted string sequence.
+     */
     String[] readStringSeq();
 
+    /**
+     * Extracts a size from the stream.
+     *
+     * @return The extracted size.
+     **/
     int readSize();
 
+    /**
+     * Extracts a proxy from the stream.
+     *
+     * @return The extracted proxy.
+     **/
     ObjectPrx readProxy();
 
+    /**
+     * Extracts the index of a Slice class from the stream.
+     *
+     * @param cb The callback to notify the application when the extracted instance is available.
+     * The Ice run time extracts Slice classes stages. The Ice run time calls <code>ReadObjectCallback.invoke</code>
+     * when the corresponding instance has been fully unmarshaled.
+     *
+     * @see ReadObjectCallback
+     **/
     void readObject(ReadObjectCallback cb);
 
+    /**
+     * Extracts a Slice type ID from the stream.
+     *
+     * @return The extracted type ID.
+     **/
     String readTypeId();
 
+    /**
+     * Extracts a user exception from the stream and throws it.
+     **/
     void throwException() throws UserException;
 
+    /**
+     * Reads the start of an object or exception slice.
+     **/
     void startSlice();
+
+    /**
+     * Indicates that the end of an object or exception slice has been reached.
+     **/
     void endSlice();
+
+    /**
+     * Skips over an object or exception slice.
+     **/
     void skipSlice();
 
+    /**
+     * Reads the start of an encapsulation.
+     **/
     void startEncapsulation();
+
+    /**
+     * Skips over an encapsulation.
+     **/
     void skipEncapsulation();
+
+    /**
+     * Indicates that the end of an encapsulation has been reached.
+     **/
     void endEncapsulation();
 
+    /**
+     * Indicates that the a sequence is about to be unmarshaled.
+     *
+     * @param numElements The number of elements in the sequence.
+     * @param minSize The minimum number of bytes required to encode a single element.
+     **/
     void startSeq(int numElements, int minSize);
+
+    /**
+     * Checks whether whether the stream has a sufficient number of bytes remaining to unmarshal
+     * the not yet unmarshaled remaining elements of a sequence. This method is used for sequences
+     * with elements whose on-the-wire size can vary (such as strings or structures containing variable-length
+     * members).
+     **/
     void checkSeq();
+
+    /**
+     * Checks whether the stream has a sufficient number of bytes remaining to unmarshal a sequence
+     * containing elements that have fixed length (such as integers or doubles).
+     *
+     * @param numElements The number of elements in the sequence.
+     * @param minSize The minimum number of bytes required to encode a single element.
+     **/
     void checkFixedSeq(int numElements, int minSize);
+
+    /**
+     * Indicates that the a sequence has been unmarshaled.
+     **/
     void endSeq(int sz);
+
+    /**
+     * Indicates that an element of a sequence with variable-length elements has been unmarshaled.
+     **/
     void endElement();
 
+    /**
+     * Indicates that unmarshaling is complete, except for any Slice objects. The application must call this method
+     * only if the stream actually contains Slice objects. Calling <code>readPendingObjects</code> triggers the
+     * calls to <code>ReadObjectCallback.invoke</code> that inform the application that unmarshaling of a Slice
+     * object is complete.
+     **/
     void readPendingObjects();
 
+    /**
+     * Resets the read position of the stream to the beginning.
+     **/
     void rewind();
 
+    /**
+     * Destroys the stream and its associated resources. The application must call <code>destroy</code> prior
+     * to releasing the last reference to a stream; failure to do so may result in resource leaks.
+     **/
     void destroy();
 }
diff --git a/java/src/Ice/IntHolder.java b/java/src/Ice/IntHolder.java
index 6a0a9d356fb..ee9122c465d 100644
--- a/java/src/Ice/IntHolder.java
+++ b/java/src/Ice/IntHolder.java
@@ -9,18 +9,32 @@
 
 package Ice;
 
+/**
+ * Holder class for integers that are in- or inout-parameters.
+ **/
 public final class IntHolder
 {
+    /**
+     * Instantiates the class with the value zero.
+     **/
     public
     IntHolder()
     {
     }
 
+    /**
+     * Instantiates the class with the passed value.
+     *
+     * The <code>int</code> value for this holder.
+     **/
     public
     IntHolder(int value)
     {
         this.value = value;
     }
 
+    /**
+     * The <code>int</code> value stored by this holder.
+     **/
     public int value;
 }
diff --git a/java/src/Ice/LinkedListHolder.java b/java/src/Ice/LinkedListHolder.java
index c208e7c183f..bdde0dfc5f0 100644
--- a/java/src/Ice/LinkedListHolder.java
+++ b/java/src/Ice/LinkedListHolder.java
@@ -9,18 +9,32 @@
 
 package Ice;
 
+/**
+ * Holder class for linked lists that are in- or inout-parameters.
+ **/
 public final class LinkedListHolder
 {
+    /**
+     * Instantiates the class with a <code>null</code> <code>LinkedList</code>.
+     **/
     public
     LinkedListHolder()
     {
     }
 
+    /**
+     * Instantiates the class with the passed <code>LinkedList</code>.
+     *
+     * @param value The <code>LinkedList</code> stored by this holder.
+     **/
     public
     LinkedListHolder(java.util.LinkedList value)
     {
         this.value = value;
     }
 
+    /**
+     * The <code>LinkedList</code> stored by this holder.
+     **/
     public java.util.LinkedList value;
 }
diff --git a/java/src/Ice/ListHolder.java b/java/src/Ice/ListHolder.java
index 17ebb98f39e..70d1ba46dd3 100644
--- a/java/src/Ice/ListHolder.java
+++ b/java/src/Ice/ListHolder.java
@@ -9,18 +9,32 @@
 
 package Ice;
 
+/**
+ * Holder class for lists that are in- or inout-parameters.
+ **/
 public final class ListHolder
 {
+    /**
+     * Instantiates the class with a <code>null</code> <code>List</code>.
+     **/
     public
     ListHolder()
     {
     }
 
+    /**
+     * Instantiates the class with the passed <code>List</code>.
+     *
+     * @param value The <code>List</code> stored by this holder.
+     **/
     public
     ListHolder(java.util.List value)
     {
         this.value = value;
     }
 
+    /**
+     * The <code>List</code> stored by this holder.
+     **/
     public java.util.List value;
 }
diff --git a/java/src/Ice/LocalException.java b/java/src/Ice/LocalException.java
index 31b5cbba85f..e95a5d2de5a 100644
--- a/java/src/Ice/LocalException.java
+++ b/java/src/Ice/LocalException.java
@@ -9,8 +9,16 @@
 
 package Ice;
 
+/**
+ * Base class for all Ice run-time exceptions.
+ **/
 public abstract class LocalException extends RuntimeException implements Cloneable
 {
+    /**
+     * Creates a copy of this exception.
+     *
+     * @return The copy of this exception.
+     **/
     public java.lang.Object clone()
     {
         java.lang.Object o = null;
@@ -25,9 +33,19 @@ public abstract class LocalException extends RuntimeException implements Cloneab
         return o;
     }
 
+    /**
+     * Returns the name of this exception.
+     *
+     * @return The name of this exception.
+     **/
     public abstract String
     ice_name();
 
+    /**
+     * Returns a string representation of this exception.
+     *
+     * @return A string representation of this exception.
+     **/
     public String
     toString()
     {
diff --git a/java/src/Ice/LoggerPlugin.java b/java/src/Ice/LoggerPlugin.java
index 3e0bbc6c94c..e9f3ddbc7d1 100644
--- a/java/src/Ice/LoggerPlugin.java
+++ b/java/src/Ice/LoggerPlugin.java
@@ -9,8 +9,22 @@
 
 package Ice;
 
+/**
+ * Class to support custom loggers. Applications using a custom logger
+ * instantiate a <code>LoggerPlugin</code> with a custom logger and
+ * return the instance from their <code>PluginFactory</code> implementation.
+ *
+ * @see PluginFactory
+ * @see Plugin
+ **/
 public class LoggerPlugin implements Ice.Plugin
 {
+    /**
+     * Installs a custom logger for a communicator.
+     *
+     * @param communicator The communicator using the custom logger.
+     * @param logger The custom logger for the communicator.
+     **/
     public 
     LoggerPlugin(Communicator communicator, Logger logger)
     {
@@ -32,14 +46,23 @@ public class LoggerPlugin implements Ice.Plugin
         instance.setLogger(logger);
     }
 
+    /**
+     * Called by the Ice run time during communicator initialization. The derived class
+     * can override this method to perform any initialization that might be required
+     * by a custom logger.
+     **/
     public void 
     initialize()
     {
     }
 
+    /**
+     * Called by the Ice run time when the communicator is destroyed. The derived class
+     * can override this method to perform any finalization that might be required
+     * by a custom logger.
+     **/
     public void
     destroy()
     {
     }
 }
-
diff --git a/java/src/Ice/LongHolder.java b/java/src/Ice/LongHolder.java
index d29b29f15c9..8488c4b1272 100644
--- a/java/src/Ice/LongHolder.java
+++ b/java/src/Ice/LongHolder.java
@@ -9,18 +9,30 @@
 
 package Ice;
 
+/**
+ * Holder class for longs that are in- or inout-parameters.
+ **/
 public final class LongHolder
 {
+    /**
+     * Instantiates the class with the value zero.
+     **/
     public
     LongHolder()
     {
     }
 
+    /**
+     * Instantiates the class with the passed value.
+     **/
     public
     LongHolder(long value)
     {
         this.value = value;
     }
 
+    /**
+     * The <code>int</code> value stored by this holder.
+     **/
     public long value;
 }
diff --git a/java/src/Ice/Object.java b/java/src/Ice/Object.java
index ba4ec721da5..4c6fd03267a 100644
--- a/java/src/Ice/Object.java
+++ b/java/src/Ice/Object.java
@@ -20,23 +20,123 @@ public interface Object
       **/
     int ice_hash();
 
+    /**
+     * Tests whether this object supports a specific Slice interface.
+     *
+     * @param s The type ID of the Slice interface to test against.
+     * @return <code>true</code> if this object has the interface
+     * specified by <code>s</code> or derives from the interface
+     * specified by <code>s</code>.
+     **/
     boolean ice_isA(String s);
+
+    /**
+     * Tests whether this object supports a specific Slice interface.
+     *
+     * @param s The type ID of the Slice interface to test against.
+     * @param current The <code>Current</code> object for the invocation.
+     * @return <code>true</code> if this object has the interface
+     * specified by <code>s</code> or derives from the interface
+     * specified by <code>s</code>.
+     **/
     boolean ice_isA(String s, Current current);
 
+    /**
+     * Tests whether this object can be reached.
+     **/
     void ice_ping();
+
+    /**
+     * Tests whether this object can be reached.
+     *
+     * @param current The <code>Current</code> object for the invocation.
+     **/
     void ice_ping(Current current);
 
+    /**
+     * Returns the Slice type IDs of the interfaces supported by this object.
+     *
+     * @return The Slice type Ids of the interfaces supported by this object, in base-to-derived
+     * order. The first element of the return array is always <code>::Ice::Object</code>.
+     **/
     String[] ice_ids();
+
+    /**
+     * Returns the Slice type IDs of the interfaces supported by this object.
+     *
+     * @param current The <code>Current</code> object for the invocation.
+     * @return The Slice type Ids of the interfaces supported by this object, in base-to-derived
+     * order. The first element of the return array is always <code>::Ice::Object</code>.
+     **/
     String[] ice_ids(Current current);
 
+    /**
+     * Returns the Slice type ID of the most-derived interface supported by this object.
+     *
+     * @return The Slice type ID of the most-derived interface.
+     **/
     String ice_id();
+
+    /**
+     * Returns the Slice type ID of the most-derived interface supported by this object.
+     *
+     * @param current The <code>Current</code> object for the invocation.
+     * @return The Slice type ID of the most-derived interface.
+     **/
     String ice_id(Current current);
 
+    /**
+     * Returns the Freeze metadata attributes for an operation.
+     *
+     * @param The name of the operation.
+     * @return The least significant bit indicates whether the operation is a read
+     * or write operation. If the bit is set, the operation is a write operation.
+     * The expression <code>ice_operationAttributes("op") & 0x1</code> is true if
+     * the operation has a <code>["freeze:write"]</code> metadata directive.
+     * <p>
+     * The second- and third least significant bit indicate the transactional mode
+     * of the operation. The expression <code>ice_operationAttributes("op") & 0x6 >> 1</code>
+     * indicates the transactional mode as follows:
+     * <dl>
+     *   <dt>0</dt>
+     *   <dd><code>["freeze:read:supports"]</code></dd>
+     *   <dt>1</dt>
+     *   <dd><code>["freeze:read:mandatory"]</code> or <code>["freeze:write:mandatory"]</code></dd>
+     *   <dt>2</dt>
+     *   <dd><code>["freeze:read:required"]</code> or <code>["freeze:write:required"]</code></dd>
+     *   <dt>3</dt>
+     *   <dd><code>["freeze:read:never"]</code></dd>
+     * </dl>
+     *
+     * @see Freeze:TransactionalEvictor
+     **/
     int ice_operationAttributes(String operation);
 
+    /**
+     * The Ice run time invokes this method prior to marshaling an object's data members. This allows a subclass
+     * to override this method in order to validate its data members.
+     **/
     void ice_preMarshal();
+
+    /**
+     * This Ice run time invokes this method vafter unmarshaling an object's data members. This allows a
+     * subclass to override this method in order to perform additional initialization.
+     **/
     void ice_postUnmarshal();
 
+    /**
+     * Dispatches an invocation to a servant. This method is used by dispatch interceptors to forward an invocation
+     * to a servant (or to another interceptor).
+     *
+     * @param request The details of the invocation.
+     * @param cb The callback object for asynchchronous dispatch. For synchronous dispatch, the callback object
+     * must be <code>null</code>.
+     * @return The dispatch status for the operation.
+     *
+     * @see DispatchInterceptor
+     * @see DispatchInterceptorAsyncCallback
+     * @see DispatchStatus
+     **/
     DispatchStatus ice_dispatch(Request request, DispatchInterceptorAsyncCallback cb);
 
     DispatchStatus __dispatch(IceInternal.Incoming in, Current current);
diff --git a/java/src/Ice/ObjectHolder.java b/java/src/Ice/ObjectHolder.java
index 6c31f835607..9201f7ce4af 100644
--- a/java/src/Ice/ObjectHolder.java
+++ b/java/src/Ice/ObjectHolder.java
@@ -9,27 +9,51 @@
 
 package Ice;
 
+/**
+ * Holder class for Ice objects that are in- or inout-parameters.
+ **/
 public final class ObjectHolder
 {
+    /**
+     * Instantiates the class with a <code>null</code> value.
+     **/
     public
     ObjectHolder()
     {
     }
 
+    /**
+     * Instantiates the class with the passed Ice object.
+     **/
     public
     ObjectHolder(Ice.Object value)
     {
         this.value = value;
     }
 
+    /**
+     * This class allows the unmarshaling code to patch the reference
+     * to the Ice object in this holder once the Ice object has been unmarshaled.
+     **/
     public class Patcher implements IceInternal.Patcher
     {
+	/**
+	 * Sets the Ice object of this holder to the passed instance.
+	 *
+	 * @param v The new object for this holder.
+	 **/
         public void
         patch(Ice.Object v)
         {
             value = v;
         }
 
+	/**
+	 * Returns the Slice type ID of the most-derived Slice type supported
+	 * by this instance.
+	 *
+	 * @return The Slice type ID.
+	 **/
         public String
         type()
         {
@@ -37,11 +61,19 @@ public final class ObjectHolder
         }
     }
 
+    /**
+     * Returns the patcher for this Ice object.
+     *
+     * @return The patcher for this Ice object.
+     **/
     public Patcher
     getPatcher()
     {
         return new Patcher();
     }
 
+    /**
+     * The Ice object stored by this holder.
+     **/
     public Ice.Object value;
 }
diff --git a/java/src/Ice/ObjectImpl.java b/java/src/Ice/ObjectImpl.java
index c1379fd2240..b19c4d9a991 100644
--- a/java/src/Ice/ObjectImpl.java
+++ b/java/src/Ice/ObjectImpl.java
@@ -9,13 +9,25 @@
 
 package Ice;
 
+/**
+ * Base class for all Slice classes.
+ **/
 public abstract class ObjectImpl implements Object, java.lang.Cloneable, java.io.Serializable
 {
+    /**
+     * Instantiates an Ice object.
+     **/
     public
     ObjectImpl()
     {
     }
 
+    /**
+     * Returns a copy of the object. The cloned object contains field-for-field copies
+     * of the state.
+     *
+     * @return The cloned object.
+     **/
     public java.lang.Object
     clone()
     {
@@ -45,12 +57,27 @@ public abstract class ObjectImpl implements Object, java.lang.Cloneable, java.io
         "::Ice::Object"
     };
 
+    /**
+     * Tests whether this object supports a specific Slice interface.
+     *
+     * @param s The type ID of the Slice interface to test against.
+     * @return The return value is <code>true</code> if <code>s</code> is
+     * <code>::Ice::Object</code>.
+     **/
     public boolean
     ice_isA(String s)
     {
         return s.equals(__ids[0]);
     }
 
+    /**
+     * Tests whether this object supports a specific Slice interface.
+     *
+     * @param s The type ID of the Slice interface to test against.
+     * @param current The current object for the invocation.
+     * @return The return value is <code>true</code> if <code>s</code> is
+     * <code>::Ice::Object</code>.
+     **/
     public boolean
     ice_isA(String s, Current current)
     {
@@ -70,12 +97,20 @@ public abstract class ObjectImpl implements Object, java.lang.Cloneable, java.io
         return DispatchStatus.DispatchOK;
     }
 
+    /**
+     * Tests whether this object can be reached.
+     **/
     public void
     ice_ping()
     {
         // Nothing to do.
     }
 
+    /**
+     * Tests whether this object can be reached.
+     *
+     * @param current The current object for the invocation.
+     **/
     public void
     ice_ping(Current current)
     {
@@ -90,12 +125,23 @@ public abstract class ObjectImpl implements Object, java.lang.Cloneable, java.io
         return DispatchStatus.DispatchOK;
     }
 
+    /**
+     * Returns the Slice type IDs of the interfaces supported by this object.
+     *
+     * @return An array whose only element is <code>::Ice::Object</code>.
+     **/
     public String[]
     ice_ids()
     {
         return __ids;
     }
 
+    /**
+     * Returns the Slice type IDs of the interfaces supported by this object.
+     *
+     * @param current The current object for the invocation.
+     * @return An array whose only element is <code>::Ice::Object</code>.
+     **/
     public String[]
     ice_ids(Current current)
     {
@@ -112,12 +158,23 @@ public abstract class ObjectImpl implements Object, java.lang.Cloneable, java.io
         return DispatchStatus.DispatchOK;
     }
 
+    /**
+     * Returns the Slice type ID of the most-derived interface supported by this object.
+     *
+     * @return The return value is always <code>::Ice::Object</code.>
+     **/
     public String
     ice_id()
     {
         return __ids[0];
     }
 
+    /**
+     * Returns the Slice type ID of the most-derived interface supported by this object.
+     *
+     * @param current The current object for the invocation.
+     * @return The return value is always <code>::Ice::Object</code.>
+     **/
     public String
     ice_id(Current current)
     {
@@ -134,22 +191,61 @@ public abstract class ObjectImpl implements Object, java.lang.Cloneable, java.io
         return DispatchStatus.DispatchOK;
     }
 
+    /**
+     * Returns the Slice type ID of the most-derived interface supported by this object.
+     *
+     * @return The return value is always <code>::Ice::Object</code>.
+     **/
     public static String
     ice_staticId()
     {
         return __ids[0];
     }
 
+    /**
+     * Returns the Freeze metadata attributes for an operation.
+     *
+     * @param The name of the operation.
+     * @return The least significant bit indicates whether the operation is a read
+     * or write operation. If the bit is set, the operation is a write operation.
+     * The expression <code>ice_operationAttributes("op") & 0x1</code> is true if
+     * the operation has a <code>["freeze:write"]</code> metadata directive.
+     * <p>
+     * The second- and third least significant bit indicate the transactional mode
+     * of the operation. The expression <code>ice_operationAttributes("op") & 0x6 >> 1</code>
+     * indicates the transactional mode as follows:
+     * <dl>
+     *   <dt>0</dt>
+     *   <dd><code>["freeze:read:supports"]</code></dd>
+     *   <dt>1</dt>
+     *   <dd><code>["freeze:read:mandatory"]</code> or <code>["freeze:write:mandatory"]</code></dd>
+     *   <dt>2</dt>
+     *   <dd><code>["freeze:read:required"]</code> or <code>["freeze:write:required"]</code></dd>
+     *   <dt>3</dt>
+     *   <dd><code>["freeze:read:never"]</code></dd>
+     * </dl>
+     *
+     * @see Freeze:TransactionalEvictor
+     **/
     public int ice_operationAttributes(String operation)
     {
         return 0;
     }
 
+    /**
+     * The Ice run time invokes this method prior to marshaling an object's data members. This allows a subclass
+     * to override this method in order to validate its data members. This default implementation does nothing.
+     **/
     public void
     ice_preMarshal()
     {
     }
 
+    /**
+     * This Ice run time invokes this method vafter unmarshaling an object's data members. This allows a
+     * subclass to override this method in order to perform additional initialization. This default
+     * implementation does nothing.
+     **/
     public void
     ice_postUnmarshal()
     {
@@ -163,6 +259,19 @@ public abstract class ObjectImpl implements Object, java.lang.Cloneable, java.io
         "ice_ping"
     };
 
+    /**
+     * Dispatches an invocation to a servant. This method is used by dispatch interceptors to forward an invocation
+     * to a servant (or to another interceptor).
+     *
+     * @param request The details of the invocation.
+     * @param cb The callback object for asynchchronous dispatch. For synchronous dispatch, the callback object must
+     * be <code>null</code>.
+     * @return The dispatch status for the operation.
+     *
+     * @see DispatchInterceptor
+     * @see DispatchInterceptorAsyncCallback
+     * @see DispatchStatus
+     **/
     public DispatchStatus
     ice_dispatch(Request request, DispatchInterceptorAsyncCallback cb)
     {
diff --git a/java/src/Ice/ObjectInputStream.java b/java/src/Ice/ObjectInputStream.java
index f8e5ce11762..409f7781520 100644
--- a/java/src/Ice/ObjectInputStream.java
+++ b/java/src/Ice/ObjectInputStream.java
@@ -9,13 +9,19 @@
 
 package Ice;
 
-//
-// If you are attempting to deserialize a Slice type that includes a
-// proxy, you must instantiate (or subclass) Ice.ObjectInputStream and
-// supply a communicator for use in reconstructing the proxy.
-//
+/**
+ * For desrialization of Slice types that contain a proxy, the application
+ * must instantiate (of subclass) <code>ObjectInputStream</code> and supply
+ * a communicator that is used to reconstruct the proxy.
+ **/
 public class ObjectInputStream extends java.io.ObjectInputStream
 {
+    /**
+     * Instantiates this class for the specified communicator and input stream.
+     *
+     * @param communicator The communicator to use to deserialize proxies.
+     * @param stream The input stream to read from.
+     **/
     public
     ObjectInputStream(Communicator communicator, java.io.InputStream stream)
         throws java.io.IOException
@@ -24,6 +30,9 @@ public class ObjectInputStream extends java.io.ObjectInputStream
         _communicator = communicator;
     }
 
+    /**
+     * Returns the communicator for this stream.
+     **/
     public Communicator
     getCommunicator()
     {
diff --git a/java/src/Ice/ObjectPrx.java b/java/src/Ice/ObjectPrx.java
index ad428f74551..7d467544e14 100644
--- a/java/src/Ice/ObjectPrx.java
+++ b/java/src/Ice/ObjectPrx.java
@@ -9,6 +9,9 @@
 
 package Ice;
 
+/**
+ * Base interface of all object proxies.
+ **/
 public interface ObjectPrx
 {
     /**
@@ -16,90 +19,508 @@ public interface ObjectPrx
      **/
     int ice_getHash();
 
+    /**
+     * Returns the communicator that created this proxy.
+     *
+     * @return The communicator that created this proxy.
+     **/
     Communicator ice_getCommunicator();
 
+    /**
+     * Returns the stringified form of this proxy.
+     *
+     * @return The stringified proxy.
+     **/
     String ice_toString();
 
+    /**
+     * Tests whether this object supports a specific Slice interface.
+     *
+     * @param __id The type ID of the Slice interface to test against.
+     * @return <code>true</code> if the target object has the interface
+     * specified by <code>__id</code> or derives from the interface
+     * specified by <code>__id</code>.
+     **/
     boolean ice_isA(String __id);
+
+    /**
+     * Tests whether this object supports a specific Slice interface.
+     *
+     * @param __id The type ID of the Slice interface to test against.
+     * @param __context The context map for the invocation.
+     * @return <code>true</code> if the target object has the interface
+     * specified by <code>__id</code> or derives from the interface
+     * specified by <code>__id</code>.
+     **/
     boolean ice_isA(String __id, java.util.Map<String, String> __context);
 
+    /**
+     * Tests whether the target object of this proxy can be reached.
+     **/
     void ice_ping();
+
+    /**
+     * Tests whether the target object of this proxy can be reached.
+     *
+     * @param __context The context map for the invocation.
+     **/
     void ice_ping(java.util.Map<String, String> __context);
 
+    /**
+     * Returns the Slice type IDs of the interfaces supported by the target object of this proxy.
+     *
+     * @return The Slice type Ids of the interfaces supported by the target object, in base-to-derived
+     * order. The first element of the return array is always <code>::Ice::Object</code>.
+     **/
     String[] ice_ids();
+
+    /**
+     * Returns the Slice type IDs of the interfaces supported by the target object of this proxy.
+     *
+     * @return The Slice type Ids of the interfaces supported by the target object, in base-to-derived
+     * order. The first element of the return array is always <code>::Ice::Object</code>.
+     *
+     * @param __context The context map for the invocation.
+     **/
     String[] ice_ids(java.util.Map<String, String> __context);
 
+    /**
+     * Returns the Slice type ID of the most-derived interface supported by the target object of this proxy.
+     *
+     * @return The Slice type ID of the most-derived interface.
+     **/
     String ice_id();
+
+    /**
+     * Returns the Slice type ID of the most-derived interface supported by the target object of this proxy.
+     *
+     * @param __context The context map for the invocation.
+     * @return The Slice type ID of the most-derived interface.
+     **/
     String ice_id(java.util.Map<String, String> __context);
 
-    // Returns true if ok, false if user exception.
+    /**
+     * Invoke an operation dynamically.
+     *
+     * @param operation The name of the operation to invoke.
+     * @param mode The operation mode (normal or idempotent).
+     * @param inParams The encoded in-parameters for the operation.
+     * @param outParams The encoded out-paramaters and return value
+     * for the operation. The return value follows any out-parameters.
+     * @return If the operation completed successfully, the return value
+     * is <code>true</code>. If the operation raises a user exception,
+     * the return value is <code>false</code>; in this case, <code>outParams</code>
+     * contains the encoded user exception. If the operation raised an
+     * it throws it directly.
+     *
+     * @see Blobject
+     * @see OperationMode
+     **/
     boolean ice_invoke(String operation, OperationMode mode, byte[] inParams, ByteSeqHolder outParams);
+
+    /**
+     * Invoke an operation dynamically.
+     *
+     * @param operation The name of the operation to invoke.
+     * @param mode The operation mode (normal or idempotent).
+     * @param inParams The encoded in-parameters for the operation.
+     * @param outParams The encoded out-paramaters and return value
+     * for the operation. The return value follows any out-parameters.
+     * @param __context The context map for the invocation.
+     * @return If the operation was invoked synchronously (because there
+     * was no need to queue the request, the return value is <code>true</code>;
+     * otherwise, if the invocation was queued, the return value is <code>false</code>.
+     *
+     * @see Blobject
+     * @see OperationMode
+     **/
     boolean ice_invoke(String operation, OperationMode mode, byte[] inParams, ByteSeqHolder outParams,
                        java.util.Map<String, String> __context);
 
+    /**
+     * Invokes an operation dynamically and asynchronously.
+     *
+     * @param cb The callback object to notify when the operation completes.
+     * @param operation The name of the operation to invoke.
+     * @param mode The operation mode (normal or idempotent).
+     * @param inParams The encoded in-parameters for the operation.
+     * @return If the operation completed successfully, the return value
+     * is <code>true</code>. If the operation raises a user exception,
+     * the return value is <code>false</code>; in this case, <code>outParams</code>
+     * contains the encoded user exception. If the operation raised an
+     * it throws it directly.
+     *
+     * @see AMI_Object_ice_invoke
+     * @see OperationMode
+     **/
     boolean ice_invoke_async(AMI_Object_ice_invoke cb, String operation, OperationMode mode, byte[] inParams);
+
+    /**
+     * Invokes an operation dynamically and asynchronously.
+     *
+     * @param cb The callback object to notify when the operation completes.
+     * @param operation The name of the operation to invoke.
+     * @param mode The operation mode (normal or idempotent).
+     * @param inParams The encoded in-parameters for the operation.
+     * @param __context The context map for the invocation.
+     * @return If the operation completed successfully, the return value
+     * is <code>true</code>. If the operation raises a user exception,
+     * the return value is <code>false</code>; in this case, <code>outParams</code>
+     * contains the encoded user exception. If the operation raised an
+     * it throws it directly.
+     *
+     * @see AMI_Object_ice_invoke
+     * @see OperationMode
+     **/
     boolean ice_invoke_async(AMI_Object_ice_invoke cb, String operation, OperationMode mode, byte[] inParams,
                              java.util.Map<String, String> context);
 
+    /**
+     * Returns the identity embedded in this proxy.
+     *
+     * @return The identity of the target object.
+     **/
     Identity ice_getIdentity();
+
+    /**
+     * Creates a new proxy that is identical to this proxy, except for the identity.
+     *
+     * @param newIdentity The identity for the new proxy.
+     * @return The proxy with the new identity.
+     **/
     ObjectPrx ice_identity(Identity newIdentity);
 
+    /**
+     * Returns the per-proxy context for this proxy.
+     *
+     * @return The per-proxy context. If the proxy does not have a per-proxy (implicit) context, the return value
+     * is <code>null</code>.
+     **/
     java.util.Map<String, String> ice_getContext();
+
+    /**
+     * Creates a new proxy that is identical to this proxy, except for the per-proxy context.
+     *
+     * @param newContext The context for the new proxy.
+     * @return The proxy with the new per-proxy context.
+     **/
     ObjectPrx ice_context(java.util.Map<String, String> newContext);
 
+    /**
+     * Returns the facet for this proxy.
+     *
+     * @return The facet for this proxy. If the proxy uses the default facet, the return value is the empty string.
+     **/
     String ice_getFacet(); 
+
+    /**
+     * Creates a new proxy that is identical to this proxy, except for the facet.
+     *
+     * @param newFacet The facet for the new proxy.
+     * @return The proxy with the new facet.
+     **/
     ObjectPrx ice_facet(String newFacet);
 
+    /**
+     * Returns the adapter ID for this proxy.
+     *
+     * @return The adapter ID. If the proxy does not have an adapter ID, the return value is the empty string.
+     **/
     String ice_getAdapterId();
+
+    /**
+     * Creates a new proxy that is identical to this proxy, except for the adapter ID.
+     *
+     * @param newAdapterId The adapter ID for the new proxy.
+     * @return The proxy with the new adapter ID.
+     **/
     ObjectPrx ice_adapterId(String newAdapterId);
 
+    /**
+     * Returns the endpoints used by this proxy.
+     *
+     * @return The endpoints used by this proxy.
+     *
+     * @see Endpoint
+     **/
     Endpoint[] ice_getEndpoints();
+
+    /**
+     * Creates a new proxy that is identical to this proxy, except for the endpoints.
+     *
+     * @param newEndpoints The endpoints for the new proxy.
+     * @return The proxy with the new endpoints.
+     **/
     ObjectPrx ice_endpoints(Endpoint[] newEndpoints);
 
+    /**
+     * Returns the locator cache timeout of this proxy.
+     *
+     * @return The locator cache timeout value (in seconds).
+     *
+     * @see Locator
+     **/
     int ice_getLocatorCacheTimeout();
+
+    /**
+     * Creates a new proxy that is identical to this proxy, except for the locator cache timeout.
+     *
+     * @param newTimeout The new locator cache timeout (in seconds).
+     *
+     * @see Locator
+     **/
     ObjectPrx ice_locatorCacheTimeout(int newTimeout);
 
+    /**
+     * Returns whether this proxy caches connections.
+     *
+     * @return <code>true</code> if this proxy caches connections; <code>false</code>, otherwise.
+     **/
     boolean ice_isConnectionCached();
+
+    /**
+     * Creates a new proxy that is identical to this proxy, except for connection caching.
+     *
+     * @param newCache <code>true</code> if the new proxy should cache connections; <code>false</code>, otherwise.
+     * @return The new proxy with the specified caching policy.
+     **/
     ObjectPrx ice_connectionCached(boolean newCache);
 
+    /**
+     * Returns how this proxy selects endpoints (randomly or ordered).
+     *
+     * @return The endpoint selection policy.
+     *
+     * @see EndpointSelectionType
+     **/
     EndpointSelectionType ice_getEndpointSelection();
+
+    /**
+     * Creates a new proxy that is identical to this proxy, except for the endpoint selection policy.
+     *
+     * @param newType The new endpoint selection policy.
+     * @return The new proxy with the specified endpoint selection policy.
+     *
+     * @see EndpointSelectionType
+     **/
     ObjectPrx ice_endpointSelection(EndpointSelectionType newType);
 
+    /**
+     * Returns whether this proxy uses only secure endpoints.
+     *
+     * @return <code>true</code> if all endpoints for this proxy are secure; <code>false</code>, otherwise.
+     **/
     boolean ice_isSecure();
+
+    /**
+     * Creates a new proxy that is identical to this proxy, except for its endpoints.
+     *
+     * @param If <code>b</code> is <code>true</code>, only endpoints that use a secure transport are
+     * retained for the new proxy. If <code>b</code> is false, the returned proxy is identical to this proxy.
+     * @return The new proxy with possible different endpoints.k
+     **/
     ObjectPrx ice_secure(boolean b);
 
+    /**
+     * Returns whether this proxy prefers secure endpoints.
+     *
+     * @return <code>true</code> if the proxy always attempts to invoke via secure endpoints before it
+     * attempts to use insecure endpoints; <code>false</code>, otherwise;
+     **/
     boolean ice_isPreferSecure();
+
+    /**
+     * Creates a new proxy that is identical to this proxy, except for its endpoint selection policy.
+     *
+     * @param b If <code>b</code> is <code>true</code>, the new proxy will use secure endpoints for invocations
+     * and only use insecure endpoints if an invocation cannot be made via secure endpoints. If <code>b</code> is
+     * <code>false</code>, the proxy prefers insecure endpoints to secure ones.
+     * @return The new proxy with the new endpoint selection policy.
+     **/
     ObjectPrx ice_preferSecure(boolean b);
 
+    /**
+     * Returns the router for this proxy.
+     *
+     * @return The router for the proxy. If no router is configured for the proxy, the return value
+     * is <code>null</code>.
+     **/
     Ice.RouterPrx ice_getRouter();
+
+    /**
+     * Creates a new proxy that is identical to this proxy, except for the router.
+     *
+     * @param router The router for the new proxy.
+     * @return The new proxy with the specified router.
+     **/
     ObjectPrx ice_router(Ice.RouterPrx router);
 
+    /**
+     * Returns the locator for this proxy.
+     *
+     * @return The locator for this proxy. If no locator is configured, the return value is <code>null</code>.
+     **/
     Ice.LocatorPrx ice_getLocator();
+
+    /**
+     * Creates a new proxy that is identical to this proxy, except for the locator.
+     *
+     * @param The locator for the new proxy.
+     * @return The new proxy with the specified locator.
+     **/
     ObjectPrx ice_locator(Ice.LocatorPrx locator);
 
+    /**
+     * Returns whether this proxy uses collocation optimization.
+     *
+     * @return <code>true</code> if the proxy uses collocation optimization; <code>false</code>, otherwise.
+     **/
     boolean ice_isCollocationOptimized();
+
+    /**
+     * Creates a new proxy that is identical to this proxy, except for collocation optimization.
+     *
+     * @param b <code>true</code> if the new proxy enables collocation optimization; <code>false</code>, otherwise.
+     * @return The new proxy the specified collocation optimization.
+     **/
     ObjectPrx ice_collocationOptimized(boolean b);
 
+    /**
+     * Creates a new proxy that is identical to this proxy, but uses twoway invocations.
+     *
+     * @return A new proxy that uses twoway invocations.
+     **/
     ObjectPrx ice_twoway();
+
+    /**
+     * Returns whether this proxy uses twoway invocations.
+     * @return <code>true</code> if this proxy uses twoway invocations; <code>false</code>, otherwise.
+     **/
     boolean ice_isTwoway();
+
+    /**
+     * Creates a new proxy that is identical to this proxy, but uses oneway invocations.
+     *
+     * @return A new proxy that uses oneway invocations.
+     **/
     ObjectPrx ice_oneway();
+
+    /**
+     * Returns whether this proxy uses oneway invocations.
+     * @return <code>true</code> if this proxy uses oneway invocations; <code>false</code>, otherwise.
+     **/
     boolean ice_isOneway();
+
+    /**
+     * Creates a new proxy that is identical to this proxy, but uses batch oneway invocations.
+     *
+     * @return A new proxy that uses batch oneway invocations.
+     **/
     ObjectPrx ice_batchOneway();
+
+    /**
+     * Returns whether this proxy uses batch oneway invocations.
+     * @return <code>true</code> if this proxy uses batch oneway invocations; <code>false</code>, otherwise.
+     **/
     boolean ice_isBatchOneway();
+
+    /**
+     * Creates a new proxy that is identical to this proxy, but uses datagram invocations.
+     *
+     * @return A new proxy that uses datagram invocations.
+     **/
     ObjectPrx ice_datagram();
+
+    /**
+     * Returns whether this proxy uses datagram invocations.
+     * @return <code>true</code> if this proxy uses datagram invocations; <code>false</code>, otherwise.
+     **/
     boolean ice_isDatagram();
+
+    /**
+     * Creates a new proxy that is identical to this proxy, but uses batch datagram invocations.
+     *
+     * @return A new proxy that uses batch datagram invocations.
+     **/
     ObjectPrx ice_batchDatagram();
+
+    /**
+     * Returns whether this proxy uses batch datagram invocations.
+     * @return <code>true</code> if this proxy uses batch datagram invocations; <code>false</code>, otherwise.
+     **/
     boolean ice_isBatchDatagram();
 
+    /**
+     * Creates a new proxy that is identical to this proxy, except for compression.
+     *
+     * @param co <code>true</code> enables compression for the new proxy; <code>false</code>disables compression.
+     * @return A new proxy with the specified compression setting.
+     **/
     ObjectPrx ice_compress(boolean co);
+
+    /**
+     * Creates a new proxy that is identical to this proxy, except for its timeout setting.
+     *
+     * @param t The timeout for the new proxy in milliseconds.
+     * @return A new proxy with the specified timeout.
+     **/
     ObjectPrx ice_timeout(int t);
+
+    /**
+     * Creates a new proxy that is identical to this proxy, except for its connection ID.
+     *
+     * @param connectionId The connection ID for the new proxy. An empty string removes the
+     * connection ID.
+     * 
+     * @return A new proxy with the specified connection ID.
+     **/
     ObjectPrx ice_connectionId(String connectionId);
 
+    /**
+     * Returns the <code>Connection</code> for this proxy. If the proxy does not yet have an established connection,
+     * it first attempts to create a connection.
+     *
+     * @return The <code>Connection</code> for this proxy.
+     * @throws CollocationOptimizationException If the proxy uses collocation optimization and denotes a
+     * collocated object.
+     *
+     * @see Connection
+     **/
     Connection ice_getConnection();
+
+    /**
+     * Returns the cached <code>Connection</code> for this proxy. If the proxy does not yet have an established
+     * connection, it does not attempt to create a connection.
+     *
+     * @return The cached <code>Connection</code> for this proxy (<code>null</code> if the proxy does not have
+     * an established connection).
+     * @throws CollocationOptimizationException If the proxy uses collocation optimization and denotes a
+     * collocated object.
+     *
+     * @see Connection
+     **/
     Connection ice_getCachedConnection();
 
+    /**
+     * Flushes any pending batched requests for this communicator. The call blocks until the flush is complete.
+     **/
     void ice_flushBatchRequests();
+
+    /**
+     * Asynchronously flushes any pending batched requests for this communicator. The call does not block.
+     *
+     * @param cb The callback object to notify the application when the flush is complete.
+     * @return <code>true</code> if the requests were flushed immediately without blocking; <code>false</code>
+     * if the requests could not be flushed immediately.
+     **/
     boolean ice_flushBatchRequests_async(AMI_Object_ice_flushBatchRequests cb);
 
+    /**
+     * Returns whether this proxy equals the passed object. Two proxies are equal if they are equal in all respects,
+     * that is, if their object identity, endpoints timeout settings, and so on are all equal.
+     *
+     * @param r The object to compare this proxy with.
+     * @return <code>true</code> if this proxy is equal to <code>r</code>; <code>false</code>, otherwise.
+     **/
     boolean equals(java.lang.Object r);
 }
diff --git a/java/src/Ice/ObjectPrxHelper.java b/java/src/Ice/ObjectPrxHelper.java
index d22926db9ba..22c553855a8 100644
--- a/java/src/Ice/ObjectPrxHelper.java
+++ b/java/src/Ice/ObjectPrxHelper.java
@@ -11,18 +11,45 @@ package Ice;
 
 public class ObjectPrxHelper extends ObjectPrxHelperBase
 {
+    /**
+     * Casts a proxy to <code>::Ice::ObjectPrx</code>. This call contacts
+     * the server and will throw an Ice run-time exception if the target
+     * object does not exist or the server cannot be reached.
+     *
+     * @param b The proxy to cast to <code>::Ice::ObjectPrx</code>.
+     * @return <code>b</code>.
+     **/
     public static ObjectPrx
     checkedCast(Ice.ObjectPrx b)
     {
         return b;
     }
 
+    /**
+     * Casts a proxy to <code>::Ice::ObjectPrx</code>. This call contacts
+     * the server and throws an Ice run-time exception if the target
+     * object does not exist or the server cannot be reached.
+     *
+     * @param b The proxy to cast to <code>::Ice::ObjectPrx</code>.
+     * @param ctx The <code>Context</code> map for the invocation.
+     * @return <code>b</code>.
+     **/
     public static ObjectPrx
     checkedCast(Ice.ObjectPrx b, java.util.Map<String, String> ctx)
     {
         return b;
     }
 
+    /**
+     * Creates a new proxy that is identical to the passed proxy, except
+     * for its facet. This call contacts
+     * the server and throws an Ice run-time exception if the target
+     * object does not exist, the specified facet does not exist, or the server cannot be reached.
+     *
+     * @param b The proxy to cast to <code>::Ice::ObjectPrx</code>.
+     * @param f The facet for the new proxy.
+     * @return The new proxy with the specified facet.
+     **/
     public static ObjectPrx
     checkedCast(Ice.ObjectPrx b, String f)
     {
@@ -45,6 +72,17 @@ public class ObjectPrxHelper extends ObjectPrxHelperBase
         return d;
     }
 
+    /**
+     * Creates a new proxy that is identical to the passed proxy, except
+     * for its facet. This call contacts
+     * the server and throws an Ice run-time exception if the target
+     * object does not exist, the specified facet does not exist, or the server cannot be reached.
+     *
+     * @param b The proxy to cast to <code>::Ice::ObjectPrx</code>.
+     * @param f The facet for the new proxy.
+     * @param ctx The <code>Context</code> map for the invocation.
+     * @return The new proxy with the specified facet.
+     **/
     public static ObjectPrx
     checkedCast(Ice.ObjectPrx b, String f, java.util.Map<String, String> ctx)
     {
@@ -67,12 +105,27 @@ public class ObjectPrxHelper extends ObjectPrxHelperBase
         return d;
     }
 
+    /**
+     * Casts a proxy to <code>::Ice::ObjectPrx</code>. This call does
+     * not contact the server and always succeeds.
+     *
+     * @param b The proxy to cast to <code>::Ice::ObjectPrx</code>.
+     * @return <code>b</code>.
+     **/
     public static ObjectPrx
     uncheckedCast(Ice.ObjectPrx b)
     {
         return b;
     }
 
+    /**
+     * Creates a new proxy that is identical to the passed proxy, except
+     * for its facet. This call does not contact the server and always succeeds.
+     *
+     * @param b The proxy to cast to <code>::Ice::ObjectPrx</code>.
+     * @param f The facet for the new proxy.
+     * @return The new proxy with the specified facet.
+     **/
     public static ObjectPrx
     uncheckedCast(Ice.ObjectPrx b, String f)
     {
diff --git a/java/src/Ice/ObjectPrxHelperBase.java b/java/src/Ice/ObjectPrxHelperBase.java
index 1d11d5a0dd9..653c2511b62 100644
--- a/java/src/Ice/ObjectPrxHelperBase.java
+++ b/java/src/Ice/ObjectPrxHelperBase.java
@@ -9,8 +9,16 @@
 
 package Ice;
 
+/**
+ * Base class for all proxies.
+ **/
 public class ObjectPrxHelperBase implements ObjectPrx, java.io.Serializable
 {
+    /**
+     * Returns a hash code for this proxy.
+     *
+     * @return The hash code.
+     **/
     public final int
     hashCode()
     {
@@ -26,27 +34,55 @@ public class ObjectPrxHelperBase implements ObjectPrx, java.io.Serializable
         return _reference.hashCode();
     }
 
+    /**
+     * Returns the communicator that created this proxy.
+     *
+     * @return The communicator that created this proxy.
+     **/
     public final Communicator ice_getCommunicator()
     {
         return _reference.getCommunicator();
     }
 
+    /**
+     * Returns the stringified form of this proxy.
+     *
+     * @return The stringified proxy.
+     **/
     public final String toString()
     {
         return _reference.toString();
     }
 
+    /**
+     * Returns the stringified form of this proxy.
+     *
+     * @return The stringified proxy.
+     **/
     public final String ice_toString()
     {
         return toString();
     }
 
+    /**
+     * Tests whether this proxy supports a given interface.
+     *
+     * @param __id The Slice type ID of an interface.
+     * @return <code>true</code> if this proxy supports the specified interface; <code>false</code>, otherwise.
+     **/
     public final boolean
     ice_isA(String __id)
     {
         return ice_isA(__id, null, false);
     }
 
+    /**
+     * Tests whether this proxy supports a given interface.
+     *
+     * @param __id The Slice type ID of an interface.
+     * @param __context The <code>Context</code> map for the invocation.
+     * @return <code>true</code> if this proxy supports the specified interface; <code>false</code>, otherwise.
+     **/
     public final boolean
     ice_isA(String __id, java.util.Map<String, String> __context)
     {
@@ -82,12 +118,20 @@ public class ObjectPrxHelperBase implements ObjectPrx, java.io.Serializable
         }
     }
 
+    /**
+     * Tests whether the target object of this proxy can be reached.
+     **/
     public final void
     ice_ping()
     {
         ice_ping(null, false);
     }
 
+    /**
+     * Tests whether the target object of this proxy can be reached.
+     *
+     * @param __context The <code>Context</code> map for the invocation.
+     **/
     public final void
     ice_ping(java.util.Map<String, String> __context)
     {
@@ -123,12 +167,25 @@ public class ObjectPrxHelperBase implements ObjectPrx, java.io.Serializable
         }
     }
 
+    /**
+     * Returns the Slice type IDs of the interfaces supported by the target object of this proxy.
+     *
+     * @return The Slice type Ids of the interfaces supported by the target object, in base-to-derived
+     * order. The first element of the return array is always <code>::Ice::Object</code>.
+     **/
     public final String[]
     ice_ids()
     {
         return ice_ids(null, false);
     }
 
+    /**
+     * Returns the Slice type IDs of the interfaces supported by the target object of this proxy.
+     *
+     * @param __context The <code>Context</code> map for the invocation.
+     * @return The Slice type Ids of the interfaces supported by the target object, in base-to-derived
+     * order. The first element of the return array is always <code>::Ice::Object</code>.
+     **/
     public final String[]
     ice_ids(java.util.Map<String, String> __context)
     {
@@ -164,12 +221,23 @@ public class ObjectPrxHelperBase implements ObjectPrx, java.io.Serializable
         }
     }
 
+    /**
+     * Returns the Slice type ID of the most-derived interface supported by the target object of this proxy.
+     *
+     * @return The Slice type ID of the most-derived interface.
+     **/
     public final String
     ice_id()
     {
         return ice_id(null, false);
     }
 
+    /**
+     * Returns the Slice type ID of the most-derived interface supported by the target object of this proxy.
+     *
+     * @param __context The <code>Context</code> map for the invocation.
+     * @return The Slice type ID of the most-derived interface.
+     **/
     public final String
     ice_id(java.util.Map<String, String> __context)
     {
@@ -205,12 +273,45 @@ public class ObjectPrxHelperBase implements ObjectPrx, java.io.Serializable
         }
     }
 
+    /**
+     * Invoke an operation dynamically.
+     *
+     * @param operation The name of the operation to invoke.
+     * @param mode The operation mode (normal or idempotent).
+     * @param inParams The encoded in-parameters for the operation.
+     * @param outParams The encoded out-paramaters and return value
+     * for the operation. The return value follows any out-parameters.
+     * @return If the operation completed successfully, the return value
+     * is <code>true</code>. If the operation raises a user exception,
+     * the return value is <code>false</code>; in this case, <code>outParams</code>
+     * contains the encoded user exception. If the operation raised an
+     * it throws it directly.
+     *
+     * @see Blobject
+     * @see OperationMode
+     **/
     public final boolean
     ice_invoke(String operation, OperationMode mode, byte[] inParams, ByteSeqHolder outParams)
     {
         return ice_invoke(operation, mode, inParams, outParams, null, false);
     }
 
+    /**
+     * Invoke an operation dynamically.
+     *
+     * @param operation The name of the operation to invoke.
+     * @param mode The operation mode (normal or idempotent).
+     * @param inParams The encoded in-parameters for the operation.
+     * @param outParams The encoded out-paramaters and return value
+     * for the operation. The return value follows any out-parameters.
+     * @param __context The context map for the invocation.
+     * @return If the operation was invoked synchronously (because there
+     * was no need to queue the request, the return value is <code>true</code>;
+     * otherwise, if the invocation was queued, the return value is <code>false</code>.
+     *
+     * @see Blobject
+     * @see OperationMode
+     **/
     public final boolean
     ice_invoke(String operation, OperationMode mode, byte[] inParams, ByteSeqHolder outParams,
                java.util.Map<String, String> context)
@@ -254,6 +355,22 @@ public class ObjectPrxHelperBase implements ObjectPrx, java.io.Serializable
         }
     }
 
+    /**
+     * Invokes an operation dynamically and asynchronously.
+     *
+     * @param cb The callback object to notify when the operation completes.
+     * @param operation The name of the operation to invoke.
+     * @param mode The operation mode (normal or idempotent).
+     * @param inParams The encoded in-parameters for the operation.
+     * @return If the operation completed successfully, the return value
+     * is <code>true</code>. If the operation raises a user exception,
+     * the return value is <code>false</code>; in this case, <code>outParams</code>
+     * contains the encoded user exception. If the operation raised an
+     * it throws it directly.
+     *
+     * @see AMI_Object_ice_invoke
+     * @see OperationMode
+     **/
     public final boolean
     ice_invoke_async(AMI_Object_ice_invoke cb, String operation, OperationMode mode, byte[] inParams)
     {
@@ -261,6 +378,23 @@ public class ObjectPrxHelperBase implements ObjectPrx, java.io.Serializable
         return cb.__invoke(this, operation, mode, inParams, null);
     }
 
+    /**
+     * Invokes an operation dynamically and asynchronously.
+     *
+     * @param cb The callback object to notify when the operation completes.
+     * @param operation The name of the operation to invoke.
+     * @param mode The operation mode (normal or idempotent).
+     * @param inParams The encoded in-parameters for the operation.
+     * @param __context The context map for the invocation.
+     * @return If the operation completed successfully, the return value
+     * is <code>true</code>. If the operation raises a user exception,
+     * the return value is <code>false</code>; in this case, <code>outParams</code>
+     * contains the encoded user exception. If the operation raised an
+     * it throws it directly.
+     *
+     * @see AMI_Object_ice_invoke
+     * @see OperationMode
+     **/
     public final boolean
     ice_invoke_async(AMI_Object_ice_invoke cb, String operation, OperationMode mode, byte[] inParams,
                      java.util.Map<String, String> context)
@@ -273,12 +407,23 @@ public class ObjectPrxHelperBase implements ObjectPrx, java.io.Serializable
         return cb.__invoke(this, operation, mode, inParams, context);
     }
     
+    /**
+     * Returns the identity embedded in this proxy.
+     *
+     * @return The identity of the target object.
+     **/
     public final Identity
     ice_getIdentity()
     {
         return _reference.getIdentity();
     }
 
+    /**
+     * Creates a new proxy that is identical to this proxy, except for the identity.
+     *
+     * @param newIdentity The identity for the new proxy.
+     * @return The proxy with the new identity.
+     **/
     public final ObjectPrx
     ice_identity(Identity newIdentity)
     {
@@ -298,24 +443,47 @@ public class ObjectPrxHelperBase implements ObjectPrx, java.io.Serializable
         }
     }
 
+    /**
+     * Returns the per-proxy context for this proxy.
+     *
+     * @return The per-proxy context. If the proxy does not have a per-proxy (implicit) context, the return value
+     * is <code>null</code>.
+     **/
     public final java.util.Map<String, String>
     ice_getContext()
     {
         return _reference.getContext();
     }
 
+    /**
+     * Creates a new proxy that is identical to this proxy, except for the per-proxy context.
+     *
+     * @param newContext The context for the new proxy.
+     * @return The proxy with the new per-proxy context.
+     **/
     public final ObjectPrx
     ice_context(java.util.Map<String, String> newContext)
     {
         return newInstance(_reference.changeContext(newContext));
     }
 
+    /**
+     * Returns the facet for this proxy.
+     *
+     * @return The facet for this proxy. If the proxy uses the default facet, the return value is the empty string.
+     **/
     public final String
     ice_getFacet()
     {
         return _reference.getFacet();
     }
 
+    /**
+     * Creates a new proxy that is identical to this proxy, except for the facet.
+     *
+     * @param newFacet The facet for the new proxy.
+     * @return The proxy with the new facet.
+     **/
     public final ObjectPrx
     ice_facet(String newFacet)
     {
@@ -336,12 +504,23 @@ public class ObjectPrxHelperBase implements ObjectPrx, java.io.Serializable
         }
     }
 
+    /**
+     * Returns the adapter ID for this proxy.
+     *
+     * @return The adapter ID. If the proxy does not have an adapter ID, the return value is the empty string.
+     **/
     public final String
     ice_getAdapterId()
     {
         return _reference.getAdapterId();
     }
 
+    /**
+     * Creates a new proxy that is identical to this proxy, except for the adapter ID.
+     *
+     * @param newAdapterId The adapter ID for the new proxy.
+     * @return The proxy with the new adapter ID.
+     **/
     public final ObjectPrx
     ice_adapterId(String newAdapterId)
     {
@@ -360,12 +539,25 @@ public class ObjectPrxHelperBase implements ObjectPrx, java.io.Serializable
         }
     }
 
+    /**
+     * Returns the endpoints used by this proxy.
+     *
+     * @return The endpoints used by this proxy.
+     *
+     * @see Endpoint
+     **/
     public final Endpoint[]
     ice_getEndpoints()
     {
         return _reference.getEndpoints();
     }
 
+    /**
+     * Creates a new proxy that is identical to this proxy, except for the endpoints.
+     *
+     * @param newEndpoints The endpoints for the new proxy.
+     * @return The proxy with the new endpoints.
+     **/
     public final ObjectPrx
     ice_endpoints(Endpoint[] newEndpoints)
     {
@@ -381,12 +573,26 @@ public class ObjectPrxHelperBase implements ObjectPrx, java.io.Serializable
         }
     }
 
+    /**
+     * Returns the locator cache timeout of this proxy.
+     *
+     * @return The locator cache timeout value (in seconds).
+     *
+     * @see Locator
+     **/
     public final int
     ice_getLocatorCacheTimeout()
     {
         return _reference.getLocatorCacheTimeout();
     }
 
+    /**
+     * Creates a new proxy that is identical to this proxy, except for the locator cache timeout.
+     *
+     * @param newTimeout The new locator cache timeout (in seconds).
+     *
+     * @see Locator
+     **/
     public final ObjectPrx
     ice_locatorCacheTimeout(int newTimeout)
     {
@@ -400,12 +606,23 @@ public class ObjectPrxHelperBase implements ObjectPrx, java.io.Serializable
         }
     }
 
+    /**
+     * Returns whether this proxy caches connections.
+     *
+     * @return <code>true</code> if this proxy caches connections; <code>false</code>, otherwise.
+     **/
     public final boolean
     ice_isConnectionCached()
     {
         return _reference.getCacheConnection();
     }
 
+    /**
+     * Creates a new proxy that is identical to this proxy, except for connection caching.
+     *
+     * @param newCache <code>true</code> if the new proxy should cache connections; <code>false</code>, otherwise.
+     * @return The new proxy with the specified caching policy.
+     **/
     public final ObjectPrx
     ice_connectionCached(boolean newCache)
     {
@@ -419,12 +636,27 @@ public class ObjectPrxHelperBase implements ObjectPrx, java.io.Serializable
         }
     }
 
+    /**
+     * Returns how this proxy selects endpoints (randomly or ordered).
+     *
+     * @return The endpoint selection policy.
+     *
+     * @see EndpointSelectionType
+     **/
     public final Ice.EndpointSelectionType
     ice_getEndpointSelection()
     {
         return _reference.getEndpointSelection();
     }
 
+    /**
+     * Creates a new proxy that is identical to this proxy, except for the endpoint selection policy.
+     *
+     * @param newType The new endpoint selection policy.
+     * @return The new proxy with the specified endpoint selection policy.
+     *
+     * @see EndpointSelectionType
+     **/
     public final ObjectPrx
     ice_endpointSelection(Ice.EndpointSelectionType newType)
     {
@@ -438,12 +670,24 @@ public class ObjectPrxHelperBase implements ObjectPrx, java.io.Serializable
         }
     }
 
+    /**
+     * Returns whether this proxy uses only secure endpoints.
+     *
+     * @return <code>true</code> if all endpoints for this proxy are secure; <code>false</code>, otherwise.
+     **/
     public final boolean
     ice_isSecure()
     {
         return _reference.getSecure();
     }
 
+    /**
+     * Creates a new proxy that is identical to this proxy, except for its endpoints.
+     *
+     * @param If <code>b</code> is <code>true</code>, only endpoints that use a secure transport are
+     * retained for the new proxy. If <code>b</code> is false, the returned proxy is identical to this proxy.
+     * @return The new proxy with possible different endpoints.k
+     **/
     public final ObjectPrx
     ice_secure(boolean b)
     {
@@ -457,12 +701,26 @@ public class ObjectPrxHelperBase implements ObjectPrx, java.io.Serializable
         }
     }
 
+    /**
+     * Returns whether this proxy prefers secure endpoints.
+     *
+     * @return <code>true</code> if the proxy always attempts to invoke via secure endpoints before it
+     * attempts to use insecure endpoints; <code>false</code>, otherwise;
+     **/
     public final boolean
     ice_isPreferSecure()
     {
         return _reference.getPreferSecure();
     }
 
+    /**
+     * Creates a new proxy that is identical to this proxy, except for its endpoint selection policy.
+     *
+     * @param b If <code>b</code> is <code>true</code>, the new proxy will use secure endpoints for invocations
+     * and only use insecure endpoints if an invocation cannot be made via secure endpoints. If <code>b</code> is
+     * <code>false</code>, the proxy prefers insecure endpoints to secure ones.
+     * @return The new proxy with the new endpoint selection policy.
+     **/
     public final ObjectPrx
     ice_preferSecure(boolean b)
     {
@@ -476,6 +734,12 @@ public class ObjectPrxHelperBase implements ObjectPrx, java.io.Serializable
         }
     }
 
+    /**
+     * Returns the router for this proxy.
+     *
+     * @return The router for the proxy. If no router is configured for the proxy, the return value
+     * is <code>null</code>.
+     **/
     public final Ice.RouterPrx
     ice_getRouter()
     {
@@ -483,6 +747,12 @@ public class ObjectPrxHelperBase implements ObjectPrx, java.io.Serializable
         return ri != null ? ri.getRouter() : null;
     }
 
+    /**
+     * Creates a new proxy that is identical to this proxy, except for the router.
+     *
+     * @param router The router for the new proxy.
+     * @return The new proxy with the specified router.
+     **/
     public final ObjectPrx
     ice_router(Ice.RouterPrx router)
     {
@@ -497,6 +767,11 @@ public class ObjectPrxHelperBase implements ObjectPrx, java.io.Serializable
         }
     }
 
+    /**
+     * Returns the locator for this proxy.
+     *
+     * @return The locator for this proxy. If no locator is configured, the return value is <code>null</code>.
+     **/
     public final Ice.LocatorPrx
     ice_getLocator()
     {
@@ -504,6 +779,12 @@ public class ObjectPrxHelperBase implements ObjectPrx, java.io.Serializable
         return ri != null ? ri.getLocator() : null;
     }
 
+    /**
+     * Creates a new proxy that is identical to this proxy, except for the locator.
+     *
+     * @param The locator for the new proxy.
+     * @return The new proxy with the specified locator.
+     **/
     public final ObjectPrx
     ice_locator(Ice.LocatorPrx locator)
     {
@@ -518,12 +799,23 @@ public class ObjectPrxHelperBase implements ObjectPrx, java.io.Serializable
         }
     }
 
+    /**
+     * Returns whether this proxy uses collocation optimization.
+     *
+     * @return <code>true</code> if the proxy uses collocation optimization; <code>false</code>, otherwise.
+     **/
     public final boolean
     ice_isCollocationOptimized()
     {
         return _reference.getCollocationOptimized();
     }
 
+    /**
+     * Creates a new proxy that is identical to this proxy, except for collocation optimization.
+     *
+     * @param b <code>true</code> if the new proxy enables collocation optimization; <code>false</code>, otherwise.
+     * @return The new proxy the specified collocation optimization.
+     **/
     public final ObjectPrx
     ice_collocationOptimized(boolean b)
     {
@@ -537,6 +829,11 @@ public class ObjectPrxHelperBase implements ObjectPrx, java.io.Serializable
         }
     }
 
+    /**
+     * Creates a new proxy that is identical to this proxy, but uses twoway invocations.
+     *
+     * @return A new proxy that uses twoway invocations.
+     **/
     public final ObjectPrx
     ice_twoway()
     {
@@ -550,12 +847,21 @@ public class ObjectPrxHelperBase implements ObjectPrx, java.io.Serializable
         }
     }
 
+    /**
+     * Returns whether this proxy uses twoway invocations.
+     * @return <code>true</code> if this proxy uses twoway invocations; <code>false</code>, otherwise.
+     **/
     public final boolean
     ice_isTwoway()
     {
         return _reference.getMode() == IceInternal.Reference.ModeTwoway;
     }
 
+    /**
+     * Creates a new proxy that is identical to this proxy, but uses oneway invocations.
+     *
+     * @return A new proxy that uses oneway invocations.
+     **/
     public final ObjectPrx
     ice_oneway()
     {
@@ -569,12 +875,21 @@ public class ObjectPrxHelperBase implements ObjectPrx, java.io.Serializable
         }
     }
 
+    /**
+     * Returns whether this proxy uses oneway invocations.
+     * @return <code>true</code> if this proxy uses oneway invocations; <code>false</code>, otherwise.
+     **/
     public final boolean
     ice_isOneway()
     {
         return _reference.getMode() == IceInternal.Reference.ModeOneway;
     }
 
+    /**
+     * Creates a new proxy that is identical to this proxy, but uses batch oneway invocations.
+     *
+     * @return A new proxy that uses batch oneway invocations.
+     **/
     public final ObjectPrx
     ice_batchOneway()
     {
@@ -588,12 +903,21 @@ public class ObjectPrxHelperBase implements ObjectPrx, java.io.Serializable
         }
     }
 
+    /**
+     * Returns whether this proxy uses batch oneway invocations.
+     * @return <code>true</code> if this proxy uses batch oneway invocations; <code>false</code>, otherwise.
+     **/
     public final boolean
     ice_isBatchOneway()
     {
         return _reference.getMode() == IceInternal.Reference.ModeBatchOneway;
     }
 
+    /**
+     * Creates a new proxy that is identical to this proxy, but uses datagram invocations.
+     *
+     * @return A new proxy that uses datagram invocations.
+     **/
     public final ObjectPrx
     ice_datagram()
     {
@@ -607,12 +931,21 @@ public class ObjectPrxHelperBase implements ObjectPrx, java.io.Serializable
         }
     }
 
+    /**
+     * Returns whether this proxy uses datagram invocations.
+     * @return <code>true</code> if this proxy uses datagram invocations; <code>false</code>, otherwise.
+     **/
     public final boolean
     ice_isDatagram()
     {
         return _reference.getMode() == IceInternal.Reference.ModeDatagram;
     }
 
+    /**
+     * Creates a new proxy that is identical to this proxy, but uses batch datagram invocations.
+     *
+     * @return A new proxy that uses batch datagram invocations.
+     **/
     public final ObjectPrx
     ice_batchDatagram()
     {
@@ -626,12 +959,22 @@ public class ObjectPrxHelperBase implements ObjectPrx, java.io.Serializable
         }
     }
 
+    /**
+     * Returns whether this proxy uses batch datagram invocations.
+     * @return <code>true</code> if this proxy uses batch datagram invocations; <code>false</code>, otherwise.
+     **/
     public final boolean
     ice_isBatchDatagram()
     {
         return _reference.getMode() == IceInternal.Reference.ModeBatchDatagram;
     }
 
+    /**
+     * Creates a new proxy that is identical to this proxy, except for compression.
+     *
+     * @param co <code>true</code> enables compression for the new proxy; <code>false</code>disables compression.
+     * @return A new proxy with the specified compression setting.
+     **/
     public final ObjectPrx
     ice_compress(boolean co)
     {
@@ -646,6 +989,12 @@ public class ObjectPrxHelperBase implements ObjectPrx, java.io.Serializable
         }
     }
 
+    /**
+     * Creates a new proxy that is identical to this proxy, except for its timeout setting.
+     *
+     * @param t The timeout for the new proxy in milliseconds.
+     * @return A new proxy with the specified timeout.
+     **/
     public final ObjectPrx
     ice_timeout(int t)
     {
@@ -660,6 +1009,14 @@ public class ObjectPrxHelperBase implements ObjectPrx, java.io.Serializable
         }
     }
 
+    /**
+     * Creates a new proxy that is identical to this proxy, except for its connection ID.
+     *
+     * @param connectionId The connection ID for the new proxy. An empty string removes the
+     * connection ID.
+     * 
+     * @return A new proxy with the specified connection ID.
+     **/
     public final ObjectPrx
     ice_connectionId(String id)
     {
@@ -674,6 +1031,16 @@ public class ObjectPrxHelperBase implements ObjectPrx, java.io.Serializable
         }
     }
 
+    /**
+     * Returns the <code>Connection</code> for this proxy. If the proxy does not yet have an established connection,
+     * it first attempts to create a connection.
+     *
+     * @return The <code>Connection</code> for this proxy.
+     * @throws CollocationOptimizationException If the proxy uses collocation optimization and denotes a
+     * collocated object.
+     *
+     * @see Connection
+     **/
     public final Connection
     ice_getConnection()
     {
@@ -694,6 +1061,17 @@ public class ObjectPrxHelperBase implements ObjectPrx, java.io.Serializable
         }
     }
 
+    /**
+     * Returns the cached <code>Connection</code> for this proxy. If the proxy does not yet have an established
+     * connection, it does not attempt to create a connection.
+     *
+     * @return The cached <code>Connection</code> for this proxy (<code>null</code> if the proxy does not have
+     * an established connection).
+     * @throws CollocationOptimizationException If the proxy uses collocation optimization and denotes a
+     * collocated object.
+     *
+     * @see Connection
+     **/
     public final Connection
     ice_getCachedConnection()
     {
@@ -717,6 +1095,9 @@ public class ObjectPrxHelperBase implements ObjectPrx, java.io.Serializable
         return null;
     }
 
+    /**
+     * Flushes any pending batched requests for this communicator. The call blocks until the flush is complete.
+     **/
     public void
     ice_flushBatchRequests()
     {
@@ -738,12 +1119,26 @@ public class ObjectPrxHelperBase implements ObjectPrx, java.io.Serializable
         }
     }
 
+    /**
+     * Asynchronously flushes any pending batched requests for this communicator. The call does not block.
+     *
+     * @param cb The callback object to notify the application when the flush is complete.
+     * @return <code>true</code> if the requests were flushed immediately without blocking; <code>false</code>
+     * if the requests could not be flushed immediately.
+     **/
     public boolean
     ice_flushBatchRequests_async(AMI_Object_ice_flushBatchRequests cb)
     {
         return cb.__invoke(this);
     }
 
+    /**
+     * Returns whether this proxy equals the passed object. Two proxies are equal if they are equal in all respects,
+     * that is, if their object identity, endpoints timeout settings, and so on are all equal.
+     *
+     * @param r The object to compare this proxy with.
+     * @return <code>true</code> if this proxy is equal to <code>r</code>; <code>false</code>, otherwise.
+     **/
     public final boolean
     equals(java.lang.Object r)
     {
diff --git a/java/src/Ice/ObjectPrxHolder.java b/java/src/Ice/ObjectPrxHolder.java
index 138230a62d4..a6ef95aac42 100644
--- a/java/src/Ice/ObjectPrxHolder.java
+++ b/java/src/Ice/ObjectPrxHolder.java
@@ -9,18 +9,32 @@
 
 package Ice;
 
+/**
+ * Holder class for proxies that are in- or inout-parameters.
+ **/
 public final class ObjectPrxHolder
 {
+    /**
+     * Instantiates the class with a <code>null</code> proxy.
+     **/
     public
     ObjectPrxHolder()
     {
     }
 
+    /**
+     * Instantiates the class with the passed proxy.
+     *
+     * @param value The proxy stored this holder.
+     **/
     public
     ObjectPrxHolder(ObjectPrx value)
     {
         this.value = value;
     }
 
+    /**
+     * The proxy stored by this holder.
+     **/
     public ObjectPrx value;
 }
diff --git a/java/src/Ice/ObjectReader.java b/java/src/Ice/ObjectReader.java
index 04b651d0756..b26959b6219 100644
--- a/java/src/Ice/ObjectReader.java
+++ b/java/src/Ice/ObjectReader.java
@@ -9,8 +9,20 @@
 
 package Ice;
 
+/**
+ * Base class for extracting objects from an input stream.
+ **/
 public abstract class ObjectReader extends ObjectImpl
 {
+    /**
+     * Reads the state of this Slice class from an input stream.
+     *
+     * @param in The input stream to read from.
+     * @param rid If <code>true</code>, extraction begins by reading a Slice type ID
+     * first. If <code>false</code>, the leading type ID is not read. This is used
+     * by the unmarshaling code in case the type ID has already been read as part
+     * of other unmarshaling activities.
+     **/
     public abstract void read(InputStream in, boolean rid);
 
     public void
diff --git a/java/src/Ice/ObjectWriter.java b/java/src/Ice/ObjectWriter.java
index 0ebbb79709a..58d8069662a 100644
--- a/java/src/Ice/ObjectWriter.java
+++ b/java/src/Ice/ObjectWriter.java
@@ -9,8 +9,16 @@
 
 package Ice;
 
+/**
+ * Base class for writing Slice classes to an output stream.
+ **/
 public abstract class ObjectWriter extends ObjectImpl
 {
+    /**
+     * Writes the state of this Slice class to an output stream.
+     *
+     * @param out The stream to write to.
+     **/
     public abstract void write(OutputStream out);
 
     public void
diff --git a/java/src/Ice/OutputStream.java b/java/src/Ice/OutputStream.java
index c8d71867936..72471d6d501 100644
--- a/java/src/Ice/OutputStream.java
+++ b/java/src/Ice/OutputStream.java
@@ -9,57 +9,227 @@
 
 package Ice;
 
+/**
+ * Interface for output streams used to write Slice types to a sequence
+ * of bytes.
+ *
+ * @see InputStream
+ **/
 public interface OutputStream
 {
+    /**
+     * Returns the communicator for this input stream.
+     *
+     * @return The communicator.
+     **/
     Communicator communicator();
 
+    /**
+     * Writes a boolean to the stream.
+     *
+     * @param v The boolean to write to the stream.
+     **/
     void writeBool(boolean v);
+
+    /**
+     * Writes a sequence of booleans to the stream.
+     *
+     * @param v The sequence of booleans to write.
+     * Passing <code>null</code> causes an empty sequence to be written to the stream.
+     **/
     void writeBoolSeq(boolean[] v);
 
+    /**
+     * Writes a byte to the stream.
+     *
+     * @param v The byte to write to the stream.
+     **/
     void writeByte(byte v);
+
+    /**
+     * Writes a sequence of bytes to the stream.
+     *
+     * @param v The sequence of bytes to write.
+     * Passing <code>null</code> causes an empty sequence to be written to the stream.
+     **/
     void writeByteSeq(byte[] v);
 
     void writeSerializable(java.io.Serializable o);
 
+    /**
+     * Writes a short to the stream.
+     *
+     * @param v The short to write to the stream.
+     **/
     void writeShort(short v);
+
+    /**
+     * Writes a sequence of shorts to the stream.
+     *
+     * @param v The sequence of shorts to write.
+     * Passing <code>null</code> causes an empty sequence to be written to the stream.
+     **/
     void writeShortSeq(short[] v);
 
+    /**
+     * Writes an integer to the stream.
+     *
+     * @param v The integer to write to the stream.
+     **/
     void writeInt(int v);
+
+    /**
+     * Writes a sequence of integers to the stream.
+     *
+     * @param v The sequence of integers to write.
+     * Passing <code>null</code> causes an empty sequence to be written to the stream.
+     **/
     void writeIntSeq(int[] v);
 
+    /**
+     * Writes a long to the stream.
+     *
+     * @param v The long to write to the stream.
+     **/
     void writeLong(long v);
+
+    /**
+     * Writes a sequence of longs to the stream.
+     *
+     * @param v The sequence of longs to write.
+     * Passing <code>null</code> causes an empty sequence to be written to the stream.
+     **/
     void writeLongSeq(long[] v);
 
+    /**
+     * Writes a float to the stream.
+     *
+     * @param v The float to write to the stream.
+     **/
     void writeFloat(float v);
+
+    /**
+     * Writes a sequence of floats to the stream.
+     *
+     * @param v The sequence of floats to write.
+     * Passing <code>null</code> causes an empty sequence to be written to the stream.
+     **/
     void writeFloatSeq(float[] v);
 
+    /**
+     * Writes a double to the stream.
+     *
+     * @param v The double to write to the stream.
+     **/
     void writeDouble(double v);
+
+    /**
+     * Writes a sequence of doubles to the stream.
+     *
+     * @param v The sequence of doubles to write.
+     * Passing <code>null</code> causes an empty sequence to be written to the stream.
+     **/
     void writeDoubleSeq(double[] v);
 
+    /**
+     * Writes a string to the stream.
+     *
+     * @param v The string to write to the stream. Passing <code>null</code> causes
+     * an empty string to be written to the stream.
+     **/
     void writeString(String v);
+
+    /**
+     * Writes a sequence of strings to the stream.
+     *
+     * @param v The sequence of strings to write.
+     * Passing <code>null</code> causes an empty sequence to be written to the stream.
+     **/
     void writeStringSeq(String[] v);
 
+    /**
+     * Writes a size to the stream.
+     *
+     * @param sz The size to write.
+     **/
     void writeSize(int sz);
 
+    /**
+     * Writes a proxy to the stream.
+     *
+     * @param v The proxy to write.
+     **/
     void writeProxy(ObjectPrx v);
 
+    /**
+     * Writes a Slice class to the stream.
+     *
+     * @param v The class to write. This method writes the index of a Slice class; the state of the class is
+     * written once <code>writePendingObjects</code> is called.
+     **/
     void writeObject(Ice.Object v);
 
+    /**
+     * Writes a Slice type ID to the stream.
+     *
+     * @param id The Slice type ID to write.
+     **/
     void writeTypeId(String id);
 
+    /**
+     * Writes a user exception to the stream.
+     *
+     * @param id The user exception to write.
+     **/
     void writeException(UserException ex);
 
+    /**
+     * Writes the start of a slice to the stream.
+     **/
     void startSlice();
+
+    /**
+     * Ends the previous slice.
+     **/
     void endSlice();
 
+    /**
+     * Writes the start of an encapsulation to the stream.
+     **/
     void startEncapsulation();
+
+    /**
+     * Ends the previous encapsulation.
+     **/
     void endEncapsulation();
 
+    /**
+     * Writes the state of Slice classes whose index was previously
+     * written with <code>writeObject</code> to the stream.
+     **/
     void writePendingObjects();
 
+    /**
+     * Indicates that marshaling of a request or reply is finished.
+     *
+     * @return The byte sequence containing the encode request or reply.
+     **/
     byte[] finished();
 
+    /**
+     * Resets this output stream. This method allows the stream to be reused, to avoid creating
+     * unnecessary garbage.
+     *
+     * @param clearBuffer If <code>true</code>, the stream's internal buffer becomes eligible for
+     * garbage collection; if <code>false</code>, the stream's internal buffer is retained, to avoid
+     * creating unnecessary garbage. If retained, thh internal buffer may resized to a smaller capacity.
+     * Either way, <code>reset</code> resets the stream's writing position to zero.
+     **/
     void reset(boolean clearBuffer);
 
+    /**
+     * Destroys the stream and its associated resources. The application must call <code>destroy</code> prior
+     * to releasing the last reference to a stream; failure to do so may result in resource leaks.
+     **/
     void destroy();
 }
diff --git a/java/src/Ice/PluginFactory.java b/java/src/Ice/PluginFactory.java
index 4017d3ea0c2..e4b9913211d 100644
--- a/java/src/Ice/PluginFactory.java
+++ b/java/src/Ice/PluginFactory.java
@@ -9,7 +9,19 @@
 
 package Ice;
 
+/**
+ * Applications implement this interface to provide a plug-in factory
+ * to the Ice run time.
+ **/
 public interface PluginFactory
 {
+    /**
+     * Called by the Ice run time to create a new plug-in.
+     *
+     * @param communicator The communicator that is in the process of being initialized.
+     * @param name The name of the plug-in.
+     * @param args The arguments that are specified in the plug-ins configuration.
+     * @return The plug-in that was created by this method.
+     **/
     Plugin create(Communicator communicator, String name, String[] args);
 }
diff --git a/java/src/Ice/ProxyIdentityFacetKey.java b/java/src/Ice/ProxyIdentityFacetKey.java
index 7cf0925c66b..a30754c612a 100644
--- a/java/src/Ice/ProxyIdentityFacetKey.java
+++ b/java/src/Ice/ProxyIdentityFacetKey.java
@@ -9,13 +9,22 @@
 
 package Ice;
 
-//
-// This class wraps a proxy and supplies the necessary methods to allow
-// it to be used as a key in a hashed collection. The proxy's identity
-// and facet are used in comparisons.
-//
+/**
+ * This class wraps a proxy to allow it to be used the key for a hashed collection.
+ * The <code>hashCode</code> and <code>equals</code> methods are based on the object identity and
+ * the facet of the proxy.
+ *
+ * @see ProxyIdentityAndFacetCompare
+ * @see ProxyIdentityCompare
+ * @see ProxyIdentityKey
+ **/
 public class ProxyIdentityFacetKey
 {
+    /**
+     * Initializes this class with the passed proxy.
+     *
+     * @param proxy The proxy for this instance.
+     **/
     public
     ProxyIdentityFacetKey(Ice.ObjectPrx proxy)
     {
@@ -31,12 +40,24 @@ public class ProxyIdentityFacetKey
         _hashCode = h;
     }
 
+    /**
+     * Computes a hash value based on the object identity and the facet of the proxy.
+     *
+     * @return The hash value.
+     **/
     public int
     hashCode()
     {
         return _hashCode;
     }
 
+    /**
+     * Compares this proxy with the passed object for equality.
+     *
+     * @param obj The object to compare this proxy with.
+     * @return <code>true</code> if the passed object is a proxy with the same object
+     * identity and facet as this proxy; <code>false</code>, otherwise.
+     **/
     public boolean
     equals(java.lang.Object obj)
     {
@@ -54,6 +75,11 @@ public class ProxyIdentityFacetKey
         return false;
     }
 
+    /**
+     * Returns the proxy stored by this class.
+     *
+     * @return The proxy stored by this class.
+     **/
     public Ice.ObjectPrx
     getProxy()
     {
diff --git a/java/src/Ice/ProxyIdentityKey.java b/java/src/Ice/ProxyIdentityKey.java
index 03a29f98eeb..c1f6abc1bcc 100644
--- a/java/src/Ice/ProxyIdentityKey.java
+++ b/java/src/Ice/ProxyIdentityKey.java
@@ -9,13 +9,22 @@
 
 package Ice;
 
-//
-// This class wraps a proxy and supplies the necessary methods to allow
-// it to be used as a key in a hashed collection. Only the proxy's
-// identity is used in comparisons.
-//
+/**
+ * This class wraps a proxy to allow it to be used the key for a hashed collection.
+ * The <code>hashCode</code> and <code>equals</code> methods are based on the object identity
+ * of the proxy.
+ *
+ * @see ProxyIdentityCompare
+ * @see ProxyIdentityAndFacetCompare
+ * @see ProxyIdentityFacetKey
+ **/
 public class ProxyIdentityKey
 {
+    /**
+     * Initializes this class with the passed proxy.
+     *
+     * @param proxy The proxy for this instance.
+     **/
     public
     ProxyIdentityKey(Ice.ObjectPrx proxy)
     {
@@ -28,12 +37,24 @@ public class ProxyIdentityKey
         _hashCode = _identity.hashCode();
     }
 
+    /**
+     * Computes a hash value based on the object identity of the proxy.
+     *
+     * @return The hash value.
+     **/
     public int
     hashCode()
     {
         return _hashCode;
     }
 
+    /**
+     * Compares this proxy with the passed object for equality.
+     *
+     * @param obj The object to compare this proxy with.
+     * @return <code>true</code> if the passed object is a proxy with the same object
+     * identity; <code>false</code>, otherwise.
+     **/
     public boolean
     equals(java.lang.Object obj)
     {
diff --git a/java/src/Ice/ReadObjectCallback.java b/java/src/Ice/ReadObjectCallback.java
index 14510d30acb..1e383c23b81 100644
--- a/java/src/Ice/ReadObjectCallback.java
+++ b/java/src/Ice/ReadObjectCallback.java
@@ -9,7 +9,19 @@
 
 package Ice;
 
+/**
+ * Callback class to inform an application when a Slice class has been unmarshaled
+ * from an input stream.
+ *
+ * @see InputStream.readObject
+ **/
 public interface ReadObjectCallback
 {
+    /**
+     * The Ice run time calls this method when it has fully unmarshaled the state
+     * of a Slice class.
+     *
+     * @param obj The unmarshaled Slice class.
+     **/
     void invoke(Ice.Object obj);
 }
diff --git a/java/src/Ice/Request.java b/java/src/Ice/Request.java
index 71d472b18b4..a9e7a07080e 100644
--- a/java/src/Ice/Request.java
+++ b/java/src/Ice/Request.java
@@ -9,8 +9,23 @@
 
 package Ice;
 
+/**
+ * Interface for incoming requests.
+ **/
 public interface Request
 {   
+    /**
+     * Returns whether this request is collocated.
+     *
+     * @return <code>true</code> if the invocation was made via proxy created by the same communicator
+     * that hosts the target's object adapter; <code>false</code>, otherwise.
+     **/
     boolean isCollocated();
+
+    /**
+     * Returns the <code>Current</code> object for this the request.
+     *
+     * @return The <code>Current</code> object for this request.
+     **/
     Current getCurrent();
-}
\ No newline at end of file
+}
diff --git a/java/src/Ice/ShortHolder.java b/java/src/Ice/ShortHolder.java
index 85cda396113..9a534436ffd 100644
--- a/java/src/Ice/ShortHolder.java
+++ b/java/src/Ice/ShortHolder.java
@@ -9,18 +9,33 @@
 
 package Ice;
 
+/**
+ * Holder class for shorts that are in- or inout-parameters.
+ **/
 public final class ShortHolder
 {
+    /**
+     * Instantiates the class with the value zero.
+     **/
     public
     ShortHolder()
     {
     }
 
+    /**
+     * Instantiates the class with the passed value.
+     *
+     * The <code>short</code> value for this holder.
+     **/
     public
     ShortHolder(short value)
     {
         this.value = value;
     }
 
+    /**
+     *
+     * The <code>short</code> value stored by this holder.
+     **/
     public short value;
 }
diff --git a/java/src/Ice/SignalPolicy.java b/java/src/Ice/SignalPolicy.java
index 0d4d3ffd67f..faba3d600b3 100644
--- a/java/src/Ice/SignalPolicy.java
+++ b/java/src/Ice/SignalPolicy.java
@@ -9,27 +9,24 @@
 
 package Ice;
 
-public final class SignalPolicy
+/**
+ * The signal policy for Ice.Application signal handling.
+ *
+ * @see Ice.Application
+ **/
+public enum SignalPolicy
 {
-    private static SignalPolicy[] _values = new SignalPolicy[4];
+    /**
+     * If a signal is received, Ice.Application reacts to the signal
+     * by calling <code>destroy</code> or <code>shutdown</code> on
+     * the communicator, or by calling a custom shutdown hook installed
+     * by the application.
+     **/
+    HandleSignals,
 
-    public static final int _HandleSignals = 0;
-    public static final SignalPolicy HandleSignals = new SignalPolicy(_HandleSignals);
-    public static final int _NoSignalHandling = 1;
-    public static final SignalPolicy NoSignalHandling = new SignalPolicy(_NoSignalHandling);
-
-    public int
-    value()
-    {
-        return _value;
-    }
-
-    private
-    SignalPolicy(int val)
-    {
-        _value = val;
-        _values[val] = this;
-    }
-
-    private int _value;
+    /**
+     * Any signal that is received is not intercepted and takes the default
+     * action.
+     **/
+    NoSignalHandling
 }
diff --git a/java/src/Ice/StringHolder.java b/java/src/Ice/StringHolder.java
index ad626b7b57d..f94b83e7a88 100644
--- a/java/src/Ice/StringHolder.java
+++ b/java/src/Ice/StringHolder.java
@@ -9,18 +9,33 @@
 
 package Ice;
 
+/**
+ * Holder class for strings that are in- or inout-parameters.
+ **/
 public final class StringHolder
 {
+    /**
+     * Instantiates the class with a <code>null</code> string.
+     **/
     public
     StringHolder()
     {
     }
 
+    /**
+     * Instantiates the class with the passed value.
+     *
+     * @param value The <code>String</code> value stored by this holder.
+     **/
     public
     StringHolder(String value)
     {
         this.value = value;
     }
 
+
+    /**
+     * The <code>String</code> value stored by this holder.
+     **/
     public String value;
 }
diff --git a/java/src/Ice/ThreadNotification.java b/java/src/Ice/ThreadNotification.java
index 3c6868e93cc..41b687f8f14 100644
--- a/java/src/Ice/ThreadNotification.java
+++ b/java/src/Ice/ThreadNotification.java
@@ -9,8 +9,26 @@
 
 package Ice;
 
+/**
+ * Interface for thread notification hooks. Applications can derive
+ * a class tat implements the <code>start</code> and <code>stop</code>
+ * methods to intercept creation and destruction of threads created
+ * by the Ice run time.
+ *
+ * @see InitializationData
+ **/
 public interface ThreadNotification
 {
+    /**
+     * The Ice run time calls <code>start</code> for each new
+     * thread it creates. The call is made by newly-started thread.
+     **/
     void start();
+
+    /**
+     * The Ice run time calls <code>stop</code> before it destroys
+     * a thread. The call is made by thread that is about to be
+     * destroyed.
+     **/
     void stop();
 }
diff --git a/java/src/Ice/TieBase.java b/java/src/Ice/TieBase.java
index 1cebb81abbc..2375429948d 100644
--- a/java/src/Ice/TieBase.java
+++ b/java/src/Ice/TieBase.java
@@ -9,8 +9,22 @@
 
 package Ice;
 
+/**
+ * Interface for servants using the tie mapping.
+ **/
 public interface TieBase
 {
+    /**
+     * Returns the delegate for this tie.
+     *
+     * @return The delegate.
+     **/
     java.lang.Object ice_delegate();
+
+    /**
+     * Sets the delegate for this tie.
+     *
+     * @param delegate The delegate.
+     **/
     void ice_delegate(java.lang.Object delegate);
 }
diff --git a/java/src/Ice/UserException.java b/java/src/Ice/UserException.java
index a9fd0fd74f8..c2e5ba2c96d 100644
--- a/java/src/Ice/UserException.java
+++ b/java/src/Ice/UserException.java
@@ -9,8 +9,16 @@
 
 package Ice;
 
+/**
+ * Base class for Slice user exceptions.
+ **/
 public abstract class UserException extends Exception implements Cloneable
 {
+    /**
+     * Creates a copy of this exception.
+     *
+     * @return The copy of this exception.
+     **/
     public java.lang.Object clone()
     {
         java.lang.Object o = null;
@@ -25,9 +33,19 @@ public abstract class UserException extends Exception implements Cloneable
         return o;
     }
 
+    /**
+     * Returns the name of this exception.
+     *
+     * @return The name of this exception.
+     **/
     public abstract String
     ice_name();
 
+    /**
+     * Returns a string representation of this exception.
+     *
+     * @return A string representation of this exception.
+     **/
     public String
     toString()
     {
diff --git a/java/src/Ice/Util.java b/java/src/Ice/Util.java
index 565515a4eed..1e07bc26296 100644
--- a/java/src/Ice/Util.java
+++ b/java/src/Ice/Util.java
@@ -11,24 +11,70 @@ package Ice;
 
 public final class Util
 {
+    /**
+     * Creates a new empty property set.
+     *
+     * @return A new empty property set.
+     **/
     public static Properties
     createProperties()
     {
         return new PropertiesI();
     }
 
+    /**
+     * Creates a property set initialized from an argument vector.
+     *
+     * @param args A command-line argument vector, possibly containing
+     * options to set properties. If the command-line options include
+     * a <code>--Ice.Config</code> option, the corresponding configuration
+     * files are parsed. If the same property is set in a configuration
+     * file and in the argument vector, the argument vector takes precedence.
+     * <p>
+     * This method modifies the argument vector by removing any Ice-related options.
+     *
+     * @return A property set initialized with the property settings
+     * that were removed from <code>args</code>.
+     **/
     public static Properties
     createProperties(StringSeqHolder args)
     {
         return new PropertiesI(args, null);
     }
 
+    /**
+     * Creates a property set initialized from an argument vector.
+     *
+     * @param args A command-line argument vector, possibly containing
+     * options to set properties. If the command-line options include
+     * a <code>--Ice.Config</code> option, the corresponding configuration
+     * files are parsed. If the same property is set in a configuration
+     * file and in the argument vector, the argument vector takes precedence.
+     * <p>
+     * This method modifies the argument vector by removing any Ice-related options.
+     * @param defaults Default values for the property set. Settings in configuration
+     * files and <code>args</code> override these defaults.
+     *
+     * @return An initalized property set.
+     **/
     public static Properties
     createProperties(StringSeqHolder args, Properties defaults)
     {
         return new PropertiesI(args, defaults);
     }
 
+    /**
+     * Creates a property set initialized from an argument vector.
+     *
+     * @param args A command-line argument vector, possibly containing
+     * options to set properties. If the command-line options include
+     * a <code>--Ice.Config</code> option, the corresponding configuration
+     * files are parsed. If the same property is set in a configuration
+     * file and in the argument vector, the argument vector takes precedence.
+     *
+     * @return A property set initialized with the property settings
+     * in <code>args</code>.
+     **/
     public static Properties
     createProperties(String[] args)
     {
@@ -36,6 +82,19 @@ public final class Util
         return createProperties(argsH);
     }
 
+    /**
+     * Creates a property set initialized from an argument vector.
+     *
+     * @param args A command-line argument vector, possibly containing
+     * options to set properties. If the command-line options include
+     * a <code>--Ice.Config</code> option, the corresponding configuration
+     * files are parsed. If the same property is set in a configuration
+     * file and in the argument vector, the argument vector takes precedence.
+     * @param defaults Default values for the property set. Settings in configuration
+     * files and <code>args</code> override these defaults.
+     *
+     * @return An initalized property set.
+     **/
     public static Properties
     createProperties(String[] args, Properties defaults)
     {
@@ -43,12 +102,29 @@ public final class Util
         return createProperties(argsH, defaults);
     }
 
+    /**
+     * Creates a communicator.
+     *
+     * @param args A command-line argument vector. Any Ice-related options
+     * in this vector are used to intialize the communicator.
+     * This method modifies the argument vector by removing any Ice-related options.
+     *
+     * @return The initialized communicator.
+     **/
     public static Communicator
     initialize(StringSeqHolder args)
     {
         return initialize(args, null);
     }
 
+    /**
+     * Creates a communicator.
+     *
+     * @param args A command-line argument vector. Any Ice-related options
+     * in this vector are used to intialize the communicator.
+     *
+     * @return The initialized communicator.
+     **/
     public static Communicator
     initialize(String[] args)
     {
@@ -56,6 +132,20 @@ public final class Util
         return initialize(argsH);
     }
 
+    /**
+     * Creates a communicator.
+     *
+     * @param args A command-line argument vector. Any Ice-related options
+     * in this vector are used to intialize the communicator.
+     * This method modifies the argument vector by removing any Ice-related options.
+     *
+     * @param initData Additional intialization data. Property settings in <code>args</code>
+     * override property settings in <code>initData</code>.
+     *
+     * @return The initialized communicator.
+     *
+     * @see InitializationData
+     **/
     public static Communicator
     initialize(StringSeqHolder args, InitializationData initData)
     {
@@ -74,6 +164,19 @@ public final class Util
         return result;
     }
 
+    /**
+     * Creates a communicator.
+     *
+     * @param args A command-line argument vector. Any Ice-related options
+     * in this vector are used to intialize the communicator.
+     *
+     * @param initData Additional intialization data. Property settings in <code>args</code>
+     * override property settings in <code>initData</code>.
+     *
+     * @return The initialized communicator.
+     *
+     * @see InitializationData
+     **/
     public static Communicator
     initialize(String[] args, InitializationData initData)
     {
@@ -81,6 +184,15 @@ public final class Util
         return initialize(argsH, initData);
     }
 
+    /**
+     * Creates a communicator.
+     *
+     * @param initData Additional intialization data.
+     *
+     * @return The initialized communicator.
+     *
+     * @see InitializationData
+     **/
     public static Communicator
     initialize(InitializationData initData)
     {
@@ -98,12 +210,22 @@ public final class Util
         return result;
     }
 
+    /**
+     * Creates a communicator using a default configuration.
+     **/
     public static Communicator
     initialize()
     {
         return initialize(new InitializationData());
     }
 
+    /**
+     * Converts a string to an object identity.
+     *
+     * @param s The string to convert.
+     *
+     * @return The converted object identity.
+     **/
     public static Identity
     stringToIdentity(String s)
     {
@@ -175,6 +297,13 @@ public final class Util
         return ident;
     }
 
+    /**
+     * Converts an object identity to a string.
+     *
+     * @param ident The object identity to convert.
+     *
+     * @return The string representation of the object identity.
+     **/
     public static String
     identityToString(Identity ident)
     {
@@ -198,6 +327,19 @@ public final class Util
     	return java.util.UUID.randomUUID().toString();
     }
 
+    /**
+     * Compares the object identities of two proxies.
+     *
+     * @param lhs A proxy.
+     * @param rhs A proxy.
+     * @return -1 if the identity in <code>lhs</code> compares
+     * less than the identity in <code>rhs</code>; 0 if the identities
+     * compare equal; 1, otherwise.
+     *
+     * @see ProxyIdentityKey
+     * @see ProxyIdentityAndFacetKey
+     * @see ProxyIdentityAndFacetCompare
+     **/
     public static int
     proxyIdentityCompare(ObjectPrx lhs, ObjectPrx rhs)
     {
@@ -226,6 +368,19 @@ public final class Util
         }
     }
 
+    /**
+     * Compares the object identities and facets of two proxies.
+     *
+     * @param lhs A proxy.
+     * @param rhs A proxy.
+     * @return -1 if the identity and facet in <code>lhs</code> compare
+     * less than the identity and facet in <code>rhs</code>; 0 if the identities
+     * and facets compare equal; 1, otherwise.
+     *
+     * @see ProxyIdentityAndFacetKey
+     * @see ProxyIdentityKey
+     * @see ProxyIdentityCompare
+     **/
     public static int
     proxyIdentityAndFacetCompare(ObjectPrx lhs, ObjectPrx rhs)
     {
@@ -273,18 +428,36 @@ public final class Util
         }
     }
 
+    /**
+     * Creates an input stream for dynamic invocation and dispatch.
+     *
+     * @param communicator The communicator for the stream.
+     * @param bytes An encoded request or reply.
+     * @return The input stream.
+     **/
     public static InputStream
     createInputStream(Communicator communicator, byte[] bytes)
     {
         return new InputStreamI(communicator, bytes);
     }
 
+    /**
+     * Creates an output stream for dynamic invocation and dispatch.
+     *
+     * @param communicator The communicator for the stream.
+     * @return The output stream.
+     **/
     public static OutputStream
     createOutputStream(Communicator communicator)
     {
         return new OutputStreamI(communicator);
     }
 
+    /**
+     * Returns the process-wide logger.
+     *
+     * The process-wide logger.
+     **/
     public static Logger
     getProcessLogger()
     {
@@ -302,6 +475,11 @@ public final class Util
         }
     }
 
+    /**
+     * Changes the process-wide logger.
+     *
+     * @param The new process-wide logger.
+     **/
     public static void
     setProcessLogger(Logger logger)
     {
@@ -311,12 +489,26 @@ public final class Util
         }
     }
 
+    /**
+     * Returns the Ice version in the form <code>A.B.C,</code>, where <code>A</code> indicates the
+     * major version, <code>B</code> indicates the minor version, and <code>C</code> indicates the
+     * patch level.
+     *
+     * @return The Ice version.
+     **/
     public static String
     stringVersion()
     {
         return "3.3.1"; // "A.B.C", with A=major, B=minor, C=patch
     }
 
+    /**
+     * Returns the Ice version as an integer in the form <code>A.BB.CC</code>, where <code>A</code>
+     * indicates the major version, <code>BB</code> indicates the minor version, and <code>CC</code>
+     * indicates the patch level. For example, for Ice 3.3.1, the returned value is 30301.
+     *
+     * @return The Ice version.
+     **/
     public static int
     intVersion()
     {
diff --git a/java/src/IceUtil/Cache.java b/java/src/IceUtil/Cache.java
index 00e98e27051..2fc00d10816 100644
--- a/java/src/IceUtil/Cache.java
+++ b/java/src/IceUtil/Cache.java
@@ -9,18 +9,37 @@
 
 package IceUtil;
 
-//
-// An abstraction to efficiently populate a Cache, without holding
-// a lock while loading from a potentially slow store.
-//
+/**
+ * An abstraction to efficiently maintain a cache, without holding
+ * a lock on the entire cache while objects are being loaded from
+ * their backing store. This class is useful mainly to implement
+ * evictors, such as used by Freeze.
+ *
+ * @see Store
+ * @see Freeze.Evictor
+ **/
 
 public class Cache
 {
+    /**
+     * Initialize a cache using the specified backing store.
+     **/
     public Cache(Store store)
     {
         _store = store;
     }
 
+    /**
+     * Return the value stored for the given key from the cache.
+     *
+     * @param key The key for the object to look up in the cache.
+     *
+     * @return If the cache contains an entry for the key, the return value
+     * is the object corresponding to the key; otherwise, the return value
+     * is null. <code>getIfPinned</code> does not call load.
+     *
+     * @see Store.load
+     **/
     public Object
     getIfPinned(Object key)
     {
@@ -31,6 +50,15 @@ public class Cache
         }
     }
 
+    /**
+     * Removes the entry for the given key from the cache.
+     *
+     * @param key The key for the entry to remove.
+     *
+     * @return If the cache contains an entry for the key, the
+     * return value is the corresponding object; otherwise, the
+     * return value is <code>null</code>.
+     **/
     public Object
     unpin(Object key)
     {
@@ -41,6 +69,9 @@ public class Cache
         }
     }
 
+    /**
+     * Removes all entries from the cache.
+     **/
     public void
     clear()
     {
@@ -50,6 +81,11 @@ public class Cache
         }
     }
 
+    /**
+     * Returns the number of entries in the cache.
+     *
+     * @return The number of entries.
+     **/
     public int
     size()
     {
@@ -59,12 +95,18 @@ public class Cache
         }
     }
 
-    //
-    // Add an object to the cache without checking store
-    // If there is already an object associated with this
-    // key, the existing value remains in the map and is
-    // returned.
-    //
+    /**
+     * Adds a key-value pair to the cache.
+     * This version of <code>pin</code> does not call <code>Store.load</code> to retrieve
+     * an entry from backing store if an entry for the given key is not yet in the cache. This
+     * is useful to add a newly-created object to the cache.
+     *
+     * @param key The key for the entry.
+     * @param o The value for the entry.
+     * @return If the cache already contains an entry with the given key, the entry is
+     * unchanged and <code>pin(Object, Object)</code> returns the original value for the entry; otherwise,
+     * the entry is added and <code>pin(Object, Object)</code> returns <code>null</code>.
+     **/
     public Object
     pin(Object key, Object o)
     {
@@ -83,22 +125,38 @@ public class Cache
         }
     }
 
-    //
-    // Return an object from the cache, loading it from the
-    // store if necessary.
-    //
+    /**
+     * Returns an object from the cache.
+     * If no entry with the given key is in the cache, <code>pin</code> calls
+     * <code>load</code> to retrieve the corresponding value (if any) from the
+     * backing store.
+     *
+     * @param key The key for the entry to retrieve.
+     * @return Returns the value for the corresponding key if the cache
+     * contains an entry for the key. Otherwise, <code>pin(Object)</code> calls
+     * <code>Store.load</code> and the return value is whatever is returned by
+     * <code>load</code>; if <code>load</code> throws an exception, that exception
+     * is thrown by <code>pin(Object)</code>.
+     **/
     public Object
     pin(Object key)
     {
         return pinImpl(key, null);
     }
 
-    //
-    // Puts this key/value pair in the cache.
-    // If this key is already in the cache or store, the given
-    // key/value pair is not inserted and the existing value
-    // is returned.
-    //
+    /**
+     * Adds a key-value pair to the cache.
+     * @param key The key for the entry.
+     * @param newObj The value for the entry.
+     * @return If the cache already contains an entry for the given key,
+     * <code>putIfAbsent</code> returns the original value for that key.
+     * If no entry is for the given key is in the cache, <code>putIfAbsent</code>
+     * calls <code>load</code> to retrieve the corresponding entry (if any) from
+     * the backings store and returns the value returned by <code>load</code>.
+     * If the cache does not contain an entry for the given key and <code>load</code>
+     * does not return a value for the key, <code>putIfAbsent</code> adds the new entry
+     * and returns <code>null</code>.
+     **/
     public Object
     putIfAbsent(Object key, Object newObj)
     {
diff --git a/java/src/IceUtil/Store.java b/java/src/IceUtil/Store.java
index bbd30d4c7e5..e28248cfc46 100644
--- a/java/src/IceUtil/Store.java
+++ b/java/src/IceUtil/Store.java
@@ -9,7 +9,17 @@
 
 package IceUtil;
 
+/**
+ * A base interface for retrieving persistent objects from a backing store.
+ **/
+
 public interface Store
 {
+    /**
+     * Instantiate an object, initializing its state from a backing store.
+     *
+     * @param key The database key for the object to instantiate.
+     *
+     **/
     Object load(Object key);
 }