ICE-6864 - Java changes for Slice docs

22 files changed, 73 insertions, 79 deletions

diff --git a/java/src/Ice/src/main/java/Ice/Application.java b/java/src/Ice/src/main/java/Ice/Application.java
index d6a693b8c71..3562445becb 100644
--- a/java/src/Ice/src/main/java/Ice/Application.java
+++ b/java/src/Ice/src/main/java/Ice/Application.java
@@ -52,7 +52,7 @@ public abstract class Application
      * 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 {@link #run} returns, destroys the communicator.
+     * 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
@@ -75,10 +75,10 @@ public abstract class Application
      * 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 {@link run} returns, destroys the communicator.
+     * 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
+     * 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
@@ -122,7 +122,7 @@ public abstract class Application
      * 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 {@link #run} returns, destroys the communicator.
+     * 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
@@ -434,7 +434,7 @@ public abstract class Application
     /**
      * 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 {@link #run} returns.
+     * 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>.
      *
@@ -464,7 +464,7 @@ public abstract class Application
     }
 
     /**
-     * Clears any shutdown hooks, including any hook established with {@link #destroyOnInterrupt}code> or
+     * Clears any shutdown hooks, including any hook established with {@link #destroyOnInterrupt} or
      * {@link #shutdownOnInterrupt}.
      **/
     public static void
diff --git a/java/src/Ice/src/main/java/Ice/Callback_Object_ice_flushBatchRequests.java b/java/src/Ice/src/main/java/Ice/Callback_Object_ice_flushBatchRequests.java
index 9dba3087518..2154e37cfa4 100644
--- a/java/src/Ice/src/main/java/Ice/Callback_Object_ice_flushBatchRequests.java
+++ b/java/src/Ice/src/main/java/Ice/Callback_Object_ice_flushBatchRequests.java
@@ -10,7 +10,7 @@
 package Ice;
 
 /**
- * Callback object for {@link ObjectPrx#.begin_ice_flushBatchRequests}.
+ * Callback object for {@link ObjectPrx#begin_ice_flushBatchRequests}.
  **/
 public abstract class Callback_Object_ice_flushBatchRequests extends OnewayCallback
 {
diff --git a/java/src/Ice/src/main/java/Ice/Callback_Object_ice_getConnection.java b/java/src/Ice/src/main/java/Ice/Callback_Object_ice_getConnection.java
index bb788bb0f6e..f65533fdaf1 100644
--- a/java/src/Ice/src/main/java/Ice/Callback_Object_ice_getConnection.java
+++ b/java/src/Ice/src/main/java/Ice/Callback_Object_ice_getConnection.java
@@ -10,7 +10,7 @@
 package Ice;
 
 /**
- * Callback object for {@link ObjectPrx#.begin_ice_getConnection}.
+ * Callback object for {@link ObjectPrx#begin_ice_getConnection}.
  **/
 public abstract class Callback_Object_ice_getConnection extends IceInternal.TwowayCallback
     implements Ice.TwowayCallbackArg1<Ice.Connection>
diff --git a/java/src/Ice/src/main/java/Ice/Callback_Object_ice_id.java b/java/src/Ice/src/main/java/Ice/Callback_Object_ice_id.java
index 87d483336e2..541989f45da 100644
--- a/java/src/Ice/src/main/java/Ice/Callback_Object_ice_id.java
+++ b/java/src/Ice/src/main/java/Ice/Callback_Object_ice_id.java
@@ -10,7 +10,7 @@
 package Ice;
 
 /**
- * Callback object for {@link ObjectPrx#.begin_ice_id}.
+ * Callback object for {@link ObjectPrx#begin_ice_id}.
  **/
 public abstract class Callback_Object_ice_id extends IceInternal.TwowayCallback
     implements Ice.TwowayCallbackArg1<String>
diff --git a/java/src/Ice/src/main/java/Ice/Callback_Object_ice_ids.java b/java/src/Ice/src/main/java/Ice/Callback_Object_ice_ids.java
index 127bbd1042d..ab2ecbd5a95 100644
--- a/java/src/Ice/src/main/java/Ice/Callback_Object_ice_ids.java
+++ b/java/src/Ice/src/main/java/Ice/Callback_Object_ice_ids.java
@@ -10,7 +10,7 @@
 package Ice;
 
 /**
- * Callback object for {@link ObjectPrx#.begin_ice_ids}.
+ * Callback object for {@link ObjectPrx#begin_ice_ids}.
  **/
 public abstract class Callback_Object_ice_ids extends IceInternal.TwowayCallback
     implements Ice.TwowayCallbackArg1<String[]>
diff --git a/java/src/Ice/src/main/java/Ice/Callback_Object_ice_invoke.java b/java/src/Ice/src/main/java/Ice/Callback_Object_ice_invoke.java
index 76479f56043..a60a22ce7ff 100644
--- a/java/src/Ice/src/main/java/Ice/Callback_Object_ice_invoke.java
+++ b/java/src/Ice/src/main/java/Ice/Callback_Object_ice_invoke.java
@@ -10,7 +10,7 @@
 package Ice;
 
 /**
- * Callback object for {@link ObjectPrx#.begin_ice_invoke}.
+ * Callback object for {@link ObjectPrx#begin_ice_invoke}.
  **/
 public abstract class Callback_Object_ice_invoke
     extends IceInternal.TwowayCallback implements _Callback_Object_ice_invoke
@@ -19,7 +19,7 @@ public abstract class Callback_Object_ice_invoke
      * The Ice run time calls <code>response</code> when an asynchronous operation invocation
      * completes successfully or raises a user exception.
      *
-     * @param __ret Indicates the result of the invocation. If <code>true</code>, the operation
+     * @param ret 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
diff --git a/java/src/Ice/src/main/java/Ice/Callback_Object_ice_isA.java b/java/src/Ice/src/main/java/Ice/Callback_Object_ice_isA.java
index afa497f6461..8ccba433133 100644
--- a/java/src/Ice/src/main/java/Ice/Callback_Object_ice_isA.java
+++ b/java/src/Ice/src/main/java/Ice/Callback_Object_ice_isA.java
@@ -10,7 +10,7 @@
 package Ice;
 
 /**
- * Callback object for {@link ObjectPrx#.begin_ice_isA}.
+ * Callback object for {@link ObjectPrx#begin_ice_isA}.
  **/
 public abstract class Callback_Object_ice_isA extends IceInternal.TwowayCallback implements Ice.TwowayCallbackBool
 {
diff --git a/java/src/Ice/src/main/java/Ice/Callback_Object_ice_ping.java b/java/src/Ice/src/main/java/Ice/Callback_Object_ice_ping.java
index 4001acb4d3b..61be444f1bc 100644
--- a/java/src/Ice/src/main/java/Ice/Callback_Object_ice_ping.java
+++ b/java/src/Ice/src/main/java/Ice/Callback_Object_ice_ping.java
@@ -10,7 +10,7 @@
 package Ice;
 
 /**
- * Callback object for {@link ObjectPrx#.begin_ice_ping}.
+ * Callback object for {@link ObjectPrx#begin_ice_ping}.
  **/
 public abstract class Callback_Object_ice_ping extends OnewayCallback
 {
diff --git a/java/src/Ice/src/main/java/Ice/InitializationData.java b/java/src/Ice/src/main/java/Ice/InitializationData.java
index 026645baae8..7b7e3eeb548 100644
--- a/java/src/Ice/src/main/java/Ice/InitializationData.java
+++ b/java/src/Ice/src/main/java/Ice/InitializationData.java
@@ -12,7 +12,7 @@ package Ice;
 /**
  * A class that encapsulates data to initialize a communicator.
  *
- * @see Communicator#intialize
+ * @see Util#initialize
  * @see Properties
  * @see Logger
  * @see ThreadNotification
diff --git a/java/src/Ice/src/main/java/Ice/InputStream.java b/java/src/Ice/src/main/java/Ice/InputStream.java
index 44b46046bab..9e6987eaeb4 100644
--- a/java/src/Ice/src/main/java/Ice/InputStream.java
+++ b/java/src/Ice/src/main/java/Ice/InputStream.java
@@ -347,7 +347,7 @@ public interface InputStream
      * Determine if an optional value is available for reading.
      *
      * @param tag The tag associated with the value.
-     * @param type The optional format for the value.
+     * @param format The optional format for the value.
      * @return True if the value is present, false otherwise.
      **/
     boolean readOptional(int tag, OptionalFormat format);
diff --git a/java/src/Ice/src/main/java/Ice/Object.java b/java/src/Ice/src/main/java/Ice/Object.java
index 63a9b27c493..997c44bbe49 100644
--- a/java/src/Ice/src/main/java/Ice/Object.java
+++ b/java/src/Ice/src/main/java/Ice/Object.java
@@ -90,7 +90,7 @@ public interface Object
     /**
      * Returns the Freeze metadata attributes for an operation.
      *
-     * @param The name of the operation.
+     * @param operation 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
diff --git a/java/src/Ice/src/main/java/Ice/ObjectImpl.java b/java/src/Ice/src/main/java/Ice/ObjectImpl.java
index 391b63a7b7d..d550dc14483 100644
--- a/java/src/Ice/src/main/java/Ice/ObjectImpl.java
+++ b/java/src/Ice/src/main/java/Ice/ObjectImpl.java
@@ -175,7 +175,7 @@ public abstract class ObjectImpl implements Object, java.lang.Cloneable, java.io
      * 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 {@link IceObject}.
+     * @return A Slice type ID.
      **/
     @Override
     public String
@@ -209,7 +209,7 @@ public abstract class ObjectImpl implements Object, java.lang.Cloneable, java.io
     /**
      * Returns the Freeze metadata attributes for an operation.
      *
-     * @param The name of the operation.
+     * @param operation 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
diff --git a/java/src/Ice/src/main/java/Ice/ObjectPrx.java b/java/src/Ice/src/main/java/Ice/ObjectPrx.java
index 23112d5cdbc..64de307d0e0 100644
--- a/java/src/Ice/src/main/java/Ice/ObjectPrx.java
+++ b/java/src/Ice/src/main/java/Ice/ObjectPrx.java
@@ -1118,7 +1118,7 @@ public interface ObjectPrx
     /**
      * Asynchronously gets the connection for this proxy. The call does not block.
      *
-     * @param cb The callback object to notify the application when the operation is complete.
+     * @param __cb The callback object to notify the application when the operation is complete.
      * @return The asynchronous result object.
      **/
     AsyncResult begin_ice_getConnection(Callback_Object_ice_getConnection __cb);
@@ -1126,9 +1126,9 @@ public interface ObjectPrx
     /**
      * Asynchronously gets the connection for this proxy. The call does not block.
      *
-     * @param __responseCb The callback object to notify the application when the there is a response available.
-     * @param __exceptionCb The callback object to notify the application when the there is an exception getting
-     * connection.
+     * @param __responseCb The callback object to notify the application when there is a response available.
+     * @param __exceptionCb The callback object to notify the application when an exception occurs while getting
+     * the connection.
      * @return The asynchronous result object.
      **/
     AsyncResult begin_ice_getConnection(IceInternal.Functional_GenericCallback1<Ice.Connection> __responseCb,
@@ -1176,7 +1176,7 @@ public interface ObjectPrx
     /**
      * 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.
+     * @param __cb The callback object to notify the application when the flush is complete.
      * @return The asynchronous result object.
      **/
     AsyncResult begin_ice_flushBatchRequests(Callback_Object_ice_flushBatchRequests __cb);
@@ -1184,7 +1184,9 @@ public interface ObjectPrx
     /**
      * 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.
+     * @param __responseCb The asynchronous completion callback object.
+     * @param __exceptionCb The asynchronous exception callback object.
+     * @param __sentCb The asynchronous sent callback object.
      * @return The asynchronous result object.
      **/
     AsyncResult begin_ice_flushBatchRequests(IceInternal.Functional_VoidCallback __responseCb,
diff --git a/java/src/Ice/src/main/java/Ice/ObjectPrxHelperBase.java b/java/src/Ice/src/main/java/Ice/ObjectPrxHelperBase.java
index 6407dc9f189..00069989035 100644
--- a/java/src/Ice/src/main/java/Ice/ObjectPrxHelperBase.java
+++ b/java/src/Ice/src/main/java/Ice/ObjectPrxHelperBase.java
@@ -297,14 +297,14 @@ public class ObjectPrxHelperBase implements ObjectPrx, java.io.Serializable
     /**
      * Completes the asynchronous ice_isA request.
      *
-     * @param __result The asynchronous result.
+     * @param __r The asynchronous result.
      * @return <code>true</code> if this proxy supports the specified interface; <code>false</code>, otherwise.
      **/
     @Override
     public final boolean
-    end_ice_isA(AsyncResult __iresult)
+    end_ice_isA(AsyncResult __r)
     {
-        IceInternal.OutgoingAsync __result = IceInternal.OutgoingAsync.check(__iresult, this, __ice_isA_name);
+        IceInternal.OutgoingAsync __result = IceInternal.OutgoingAsync.check(__r, this, __ice_isA_name);
         try
         {
             if(!__result.__wait())
@@ -333,7 +333,7 @@ public class ObjectPrxHelperBase implements ObjectPrx, java.io.Serializable
         }
     }
 
-    static public void __ice_isA_completed(TwowayCallbackBool __cb, Ice.AsyncResult __result)
+    static public void __ice_isA_completed(TwowayCallbackBool __cb, AsyncResult __result)
     {
         boolean __ret = false;
         try
@@ -787,15 +787,15 @@ public class ObjectPrxHelperBase implements ObjectPrx, java.io.Serializable
     /**
      * Completes the asynchronous ice_ids request.
      *
-     * @param __result The asynchronous result.
+     * @param __r The asynchronous result.
      * @return The Slice type IDs of the interfaces supported by the target object, in base-to-derived
      * order. The first element of the returned array is always <code>::Ice::Object</code>.
      **/
     @Override
     public final String[]
-    end_ice_ids(AsyncResult __iresult)
+    end_ice_ids(AsyncResult __r)
     {
-        IceInternal.OutgoingAsync __result = IceInternal.OutgoingAsync.check(__iresult, this, __ice_ids_name);
+        IceInternal.OutgoingAsync __result = IceInternal.OutgoingAsync.check(__r, this, __ice_ids_name);
         try
         {
             if(!__result.__wait())
@@ -1063,14 +1063,14 @@ public class ObjectPrxHelperBase implements ObjectPrx, java.io.Serializable
     /**
      * Completes the asynchronous ice_id request.
      *
-     * @param __result The asynchronous result.
+     * @param __r The asynchronous result.
      * @return The Slice type ID of the most-derived interface.
      **/
     @Override
     public final String
-    end_ice_id(AsyncResult __iresult)
+    end_ice_id(AsyncResult __r)
     {
-        IceInternal.OutgoingAsync __result = IceInternal.OutgoingAsync.check(__iresult, this, __ice_id_name);
+        IceInternal.OutgoingAsync __result = IceInternal.OutgoingAsync.check(__r, this, __ice_id_name);
         try
         {
             if(!__result.__wait())
@@ -1151,7 +1151,7 @@ public class ObjectPrxHelperBase implements ObjectPrx, java.io.Serializable
      * @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.
+     * @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>.
@@ -1306,9 +1306,9 @@ public class ObjectPrxHelperBase implements ObjectPrx, java.io.Serializable
      * @param mode The operation mode (normal or idempotent).
      * @param inParams The encoded in-parameters for the operation.
      * for the operation. The return value follows any out-parameters.
-     * @param __responseCb The asynchronous response callback object.
-     * @param __exceptionCb The asynchronous exception callback object.
-     * @param __sentCb The asynchronous sent callback object.
+     * @param responseCb The asynchronous response callback object.
+     * @param exceptionCb The asynchronous exception callback object.
+     * @param sentCb The asynchronous sent callback object.
      * @return The asynchronous result object.
      *
      * @see Blobject
@@ -1330,8 +1330,8 @@ public class ObjectPrxHelperBase implements ObjectPrx, java.io.Serializable
      * @param mode The operation mode (normal or idempotent).
      * @param inParams The encoded in-parameters for the operation.
      * for the operation. The return value follows any out-parameters.
-     * @param __responseCb The asynchronous response callback object.
-     * @param __exceptionCb The asynchronous exception callback object.
+     * @param responseCb The asynchronous response callback object.
+     * @param exceptionCb The asynchronous exception callback object.
      * @return The asynchronous result object.
      *
      * @see Blobject
@@ -1351,11 +1351,11 @@ public class ObjectPrxHelperBase implements ObjectPrx, java.io.Serializable
      * @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.
+     * @param context The context map for the invocation.
      * for the operation. The return value follows any out-parameters.
-     * @param __responseCb The asynchronous response callback object.
-     * @param __exceptionCb The asynchronous exception callback object.
-     * @param __sentCb The asynchronous sent callback object.
+     * @param responseCb The asynchronous response callback object.
+     * @param exceptionCb The asynchronous exception callback object.
+     * @param sentCb The asynchronous sent callback object.
      * @return The asynchronous result object.
      *
      * @see Blobject
@@ -1377,10 +1377,10 @@ public class ObjectPrxHelperBase implements ObjectPrx, java.io.Serializable
      * @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.
+     * @param context The context map for the invocation.
      * for the operation. The return value follows any out-parameters.
-     * @param __responseCb The asynchronous response callback object.
-     * @param __exceptionCb The asynchronous exception callback object.
+     * @param responseCb The asynchronous response callback object.
+     * @param exceptionCb The asynchronous exception callback object.
      * @return The asynchronous result object.
      *
      * @see Blobject
@@ -1453,7 +1453,7 @@ public class ObjectPrxHelperBase implements ObjectPrx, java.io.Serializable
      * Completes the asynchronous ice_invoke request.
      *
      * @param outParams The encoded out-paramaters and return value.
-     * @param __result The asynchronous result.
+     * @param __r The asynchronous result.
      * @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>
@@ -1462,9 +1462,9 @@ public class ObjectPrxHelperBase implements ObjectPrx, java.io.Serializable
      **/
     @Override
     public final boolean
-    end_ice_invoke(ByteSeqHolder outParams, AsyncResult __iresult)
+    end_ice_invoke(ByteSeqHolder outParams, AsyncResult __r)
     {
-        IceInternal.OutgoingAsync __result = IceInternal.OutgoingAsync.check(__iresult, this, __ice_invoke_name);
+        IceInternal.OutgoingAsync __result = IceInternal.OutgoingAsync.check(__r, this, __ice_invoke_name);
         try
         {
             boolean ok = __result.__wait();
@@ -1853,7 +1853,7 @@ public class ObjectPrxHelperBase implements ObjectPrx, java.io.Serializable
     /**
      * 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
+     * @param b 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
      **/
@@ -1990,7 +1990,7 @@ public class ObjectPrxHelperBase implements ObjectPrx, java.io.Serializable
     /**
      * Creates a new proxy that is identical to this proxy, except for the locator.
      *
-     * @param The locator for the new proxy.
+     * @param locator The locator for the new proxy.
      * @return The new proxy with the specified locator.
      **/
     @Override
@@ -2239,7 +2239,7 @@ 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
+     * @param id The connection ID for the new proxy. An empty string removes the
      * connection ID.
      *
      * @return A new proxy with the specified connection ID.
diff --git a/java/src/Ice/src/main/java/Ice/ObjectReader.java b/java/src/Ice/src/main/java/Ice/ObjectReader.java
index a5e5fc7220f..967b1bcca12 100644
--- a/java/src/Ice/src/main/java/Ice/ObjectReader.java
+++ b/java/src/Ice/src/main/java/Ice/ObjectReader.java
@@ -18,10 +18,6 @@ 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);
 
diff --git a/java/src/Ice/src/main/java/Ice/OutputStream.java b/java/src/Ice/src/main/java/Ice/OutputStream.java
index ef327f34e8f..4b35c46f258 100644
--- a/java/src/Ice/src/main/java/Ice/OutputStream.java
+++ b/java/src/Ice/src/main/java/Ice/OutputStream.java
@@ -226,14 +226,14 @@ public interface OutputStream
      * Write an enumerated value.
      *
      * @param v The enumerator.
-     * @param limit The maximum enumerator value in the definition.
+     * @param maxValue The maximum enumerator value in the definition.
      **/
     void writeEnum(int v, int maxValue);
 
     /**
      * Writes a user exception to the stream.
      *
-     * @param id The user exception to write.
+     * @param ex The user exception to write.
      **/
     void writeException(UserException ex);
 
@@ -316,7 +316,7 @@ public interface OutputStream
      * Write the header information for an optional value.
      *
      * @param tag The numeric tag associated with the value.
-     * @param type The optional format of the value.
+     * @param format The optional format of the value.
      **/
     boolean writeOptional(int tag, Ice.OptionalFormat format);
 
@@ -347,7 +347,7 @@ public interface OutputStream
      * Computes the amount of data written since the previous call to startSize and
      * writes that value at the saved position.
      *
-     * @param The saved position.
+     * @param pos The saved position.
      **/
     void endSize(int pos);
 
diff --git a/java/src/Ice/src/main/java/Ice/ProxyIdentityFacetKey.java b/java/src/Ice/src/main/java/Ice/ProxyIdentityFacetKey.java
index 380b966512d..21ff8089ba2 100644
--- a/java/src/Ice/src/main/java/Ice/ProxyIdentityFacetKey.java
+++ b/java/src/Ice/src/main/java/Ice/ProxyIdentityFacetKey.java
@@ -14,8 +14,8 @@ package Ice;
  * 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 Util#proxyIdentityAndFacetCompare
+ * @see Util#proxyIdentityCompare
  * @see ProxyIdentityKey
  *
  **/
diff --git a/java/src/Ice/src/main/java/Ice/ProxyIdentityKey.java b/java/src/Ice/src/main/java/Ice/ProxyIdentityKey.java
index 1af26919ea4..b8c85cf324b 100644
--- a/java/src/Ice/src/main/java/Ice/ProxyIdentityKey.java
+++ b/java/src/Ice/src/main/java/Ice/ProxyIdentityKey.java
@@ -14,8 +14,8 @@ package Ice;
  * The <code>hashCode</code> and <code>equals</code> methods are based on the object identity
  * of the proxy.
  *
- * @see ProxyIdentityCompare
- * @see ProxyIdentityAndFacetCompare
+ * @see Util#proxyIdentityCompare
+ * @see Util#proxyIdentityAndFacetCompare
  * @see ProxyIdentityFacetKey
  *
  **/
diff --git a/java/src/Ice/src/main/java/Ice/TwowayCallback.java b/java/src/Ice/src/main/java/Ice/TwowayCallback.java
index a71fb7b1522..bedbe2970c6 100644
--- a/java/src/Ice/src/main/java/Ice/TwowayCallback.java
+++ b/java/src/Ice/src/main/java/Ice/TwowayCallback.java
@@ -17,14 +17,14 @@ public interface TwowayCallback
     /**
      * Called when the invocation raises an Ice run-time exception.
      *
-     * @param ex The Ice run-time exception raised by the operation.
+     * @param __ex The Ice run-time exception raised by the operation.
      **/
     public void exception(LocalException __ex);
 
     /**
      * Called when the invocation raises an Ice system exception.
      *
-     * @param ex The Ice system exception raised by the operation.
+     * @param __ex The Ice system exception raised by the operation.
      **/
     public void exception(SystemException __ex);
 }
diff --git a/java/src/Ice/src/main/java/Ice/UserExceptionReader.java b/java/src/Ice/src/main/java/Ice/UserExceptionReader.java
index e0700feac53..a1ed403606e 100644
--- a/java/src/Ice/src/main/java/Ice/UserExceptionReader.java
+++ b/java/src/Ice/src/main/java/Ice/UserExceptionReader.java
@@ -30,7 +30,7 @@ public abstract class UserExceptionReader extends UserException
      *
      * @param in The input stream.
      **/
-    public abstract void read(Ice.InputStream is);
+    public abstract void read(Ice.InputStream in);
 
     @Override
     public void __write(IceInternal.BasicStream os)
diff --git a/java/src/Ice/src/main/java/Ice/Util.java b/java/src/Ice/src/main/java/Ice/Util.java
index 5b030e82459..d6dd9f753e4 100644
--- a/java/src/Ice/src/main/java/Ice/Util.java
+++ b/java/src/Ice/src/main/java/Ice/Util.java
@@ -348,8 +348,8 @@ public final class Util
      * compare equal; 1, otherwise.
      *
      * @see ProxyIdentityKey
-     * @see ProxyIdentityAndFacetKey
-     * @see ProxyIdentityAndFacetCompare
+     * @see ProxyIdentityFacetKey
+     * @see #proxyIdentityAndFacetCompare
      **/
     public static int
     proxyIdentityCompare(ObjectPrx lhs, ObjectPrx rhs)
@@ -388,9 +388,9 @@ public final class Util
      * less than the identity and facet in <code>rhs</code>; 0 if the identities
      * and facets compare equal; 1, otherwise.
      *
-     * @see ProxyIdentityAndFacetKey
+     * @see ProxyIdentityFacetKey
      * @see ProxyIdentityKey
-     * @see ProxyIdentityCompare
+     * @see #proxyIdentityCompare
      **/
     public static int
     proxyIdentityAndFacetCompare(ObjectPrx lhs, ObjectPrx rhs)
@@ -475,8 +475,6 @@ public final class Util
      *
      * @param communicator The communicator for the stream.
      * @param bytes An encoded request or reply.
-     * @param copyBytes True if the given bytes should be copied,
-     * false otherwise.
      * @return The input stream.
      **/
     public static InputStream
@@ -492,8 +490,6 @@ public final class Util
      * @param communicator The communicator for the stream.
      * @param bytes An encoded request or reply.
      * @param v The desired encoding version.
-     * @param copyBytes True if the given bytes should be copied,
-     * false otherwise.
      * @return The input stream.
      **/
     public static InputStream
diff --git a/java/src/Ice/src/main/java/Ice/_Callback_Object_ice_invoke.java b/java/src/Ice/src/main/java/Ice/_Callback_Object_ice_invoke.java
index 35f63ce132c..6357f50555c 100644
--- a/java/src/Ice/src/main/java/Ice/_Callback_Object_ice_invoke.java
+++ b/java/src/Ice/src/main/java/Ice/_Callback_Object_ice_invoke.java
@@ -10,7 +10,7 @@
 package Ice;
 
 /**
- * Callback object for {@link ObjectPrx#.begin_ice_invoke}.
+ * Callback object for {@link ObjectPrx#begin_ice_invoke}.
  **/
 public interface _Callback_Object_ice_invoke extends Ice.TwowayCallback
 {
@@ -18,7 +18,7 @@ public interface _Callback_Object_ice_invoke extends Ice.TwowayCallback
      * The Ice run time calls <code>response</code> when an asynchronous operation invocation
      * completes successfully or raises a user exception.
      *
-     * @param __ret Indicates the result of the invocation. If <code>true</code>, the operation
+     * @param ret 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