Bug 3502 - Improve javadoc support in Eclipse

Fixed many doc comments in Java and Slice and
added doc comments for C#.

14 files changed, 60 insertions, 46 deletions

diff --git a/java/src/Ice/AMD_Object_ice_invoke.java b/java/src/Ice/AMD_Object_ice_invoke.java
index 63110e3443c..02f59a6524a 100644
--- a/java/src/Ice/AMD_Object_ice_invoke.java
+++ b/java/src/Ice/AMD_Object_ice_invoke.java
@@ -22,7 +22,7 @@ public interface AMD_Object_ice_invoke
      *
      * @param ok <code>true</code> indicates that the operation
      * completed successfully; <code>false</code> indicates that the
-     * operation raised user exception.
+     * operation raised a user exception.
      * @param outParams The encoded out-parameters for the operation or,
      * if <code>ok</code> is <code>false</code>, the encoded user exception.
      **/
@@ -36,6 +36,5 @@ public interface AMD_Object_ice_invoke
      * is a user exception, the caller receives {@link UnknownUserException}.
      * Use {@link #ice_response} to raise user exceptions.
      **/
-
     void ice_exception(java.lang.Exception ex);
 }
diff --git a/java/src/Ice/Application.java b/java/src/Ice/Application.java
index 342845bf84e..6a7f5931891 100644
--- a/java/src/Ice/Application.java
+++ b/java/src/Ice/Application.java
@@ -108,7 +108,7 @@ public abstract class Application
      * 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.
+     * @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.
      *
@@ -174,7 +174,6 @@ public abstract class Application
      * 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>.
      **/
@@ -198,7 +197,7 @@ public abstract class Application
     /**
      * 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.
+     * you cannot have more than one instance of <code>Application</code> in a program.
      *
      * @return The communicator for the application.
      **/
diff --git a/java/src/Ice/Blobject.java b/java/src/Ice/Blobject.java
index 52cfec01bb2..111b70f0089 100644
--- a/java/src/Ice/Blobject.java
+++ b/java/src/Ice/Blobject.java
@@ -22,6 +22,7 @@ public abstract class Blobject extends Ice.ObjectImpl
      * @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 current The Current object to pass to 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>
diff --git a/java/src/Ice/InputStream.java b/java/src/Ice/InputStream.java
index 2a4f897d15f..d715da08334 100644
--- a/java/src/Ice/InputStream.java
+++ b/java/src/Ice/InputStream.java
@@ -28,7 +28,7 @@ public interface InputStream
      * 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>,
+     * @param slice 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 {@link NoObjectFactoryException}.
      **/
@@ -171,7 +171,7 @@ public interface InputStream
      * 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 {@link ReadObjectCallback#invoke}
+     * The Ice run time extracts Slice classes in stages. The Ice run time calls {@link ReadObjectCallback#invoke}
      * when the corresponding instance has been fully unmarshaled.
      *
      * @see ReadObjectCallback
@@ -246,7 +246,7 @@ public interface InputStream
     void checkFixedSeq(int numElements, int minSize);
 
     /**
-     * Indicates that the a sequence has been unmarshaled.
+     * Indicates that a sequence has been unmarshaled.
      **/
     void endSeq(int sz);
 
@@ -258,7 +258,7 @@ public interface InputStream
     /**
      * 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 {@link ReadObjectCallback#invoke} that inform the application that unmarshaling of a Slice
+     * calls to {@link ReadObjectCallback#invoke} that informs the application that unmarshaling of a Slice
      * object is complete.
      **/
     void readPendingObjects();
diff --git a/java/src/Ice/Object.java b/java/src/Ice/Object.java
index 7f2b79c3c1d..9d7aa80da42 100644
--- a/java/src/Ice/Object.java
+++ b/java/src/Ice/Object.java
@@ -9,6 +9,9 @@
 
 package Ice;
 
+/**
+ * The base interface for servants.
+ **/
 public interface Object
 {
     boolean equals(java.lang.Object rhs);
@@ -56,8 +59,8 @@ public interface Object
     /**
      * 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>.
+     * @return The Slice type IDs of the interfaces supported by this object, in base-to-derived
+     * order. The first element of the returned array is always <code>::Ice::Object</code>.
      **/
     String[] ice_ids();
 
@@ -65,8 +68,8 @@ public interface Object
      * Returns the Slice type IDs of the interfaces supported by this object.
      *
      * @param current The {@link Current} 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>.
+     * @return The Slice type IDs of the interfaces supported by this object, in base-to-derived
+     * order. The first element of the returned array is always <code>::Ice::Object</code>.
      **/
     String[] ice_ids(Current current);
 
@@ -119,7 +122,7 @@ public interface Object
     void ice_preMarshal();
 
     /**
-     * This Ice run time invokes this method vafter unmarshaling an object's data members. This allows a
+     * The 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();
diff --git a/java/src/Ice/ObjectImpl.java b/java/src/Ice/ObjectImpl.java
index c3df1998d9f..fc1ea960340 100644
--- a/java/src/Ice/ObjectImpl.java
+++ b/java/src/Ice/ObjectImpl.java
@@ -192,9 +192,9 @@ 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.
+     * Returns the Slice type ID of the interface supported by this object.
      *
-     * @return The return value is always {@link IceObject}.
+     * @return The return value is always ::Ice::Object.
      **/
     public static String
     ice_staticId()
diff --git a/java/src/Ice/ObjectInputStream.java b/java/src/Ice/ObjectInputStream.java
index 409f7781520..fd15d230b80 100644
--- a/java/src/Ice/ObjectInputStream.java
+++ b/java/src/Ice/ObjectInputStream.java
@@ -10,8 +10,8 @@
 package Ice;
 
 /**
- * For desrialization of Slice types that contain a proxy, the application
- * must instantiate (of subclass) <code>ObjectInputStream</code> and supply
+ * For deserialization of Slice types that contain a proxy, the application
+ * must instantiate a subclass of <code>ObjectInputStream</code> and supply
  * a communicator that is used to reconstruct the proxy.
  **/
 public class ObjectInputStream extends java.io.ObjectInputStream
diff --git a/java/src/Ice/ObjectPrx.java b/java/src/Ice/ObjectPrx.java
index 2ef3c42575e..d1d4de3fb8f 100644
--- a/java/src/Ice/ObjectPrx.java
+++ b/java/src/Ice/ObjectPrx.java
@@ -69,16 +69,16 @@ public interface ObjectPrx
     /**
      * 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>.
+     * @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>.
      **/
     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>.
+     * @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>.
      *
      * @param __context The context map for the invocation.
      **/
@@ -100,7 +100,7 @@ public interface ObjectPrx
     String ice_id(java.util.Map<String, String> __context);
 
     /**
-     * Invoke an operation dynamically.
+     * Invokes an operation dynamically.
      *
      * @param operation The name of the operation to invoke.
      * @param mode The operation mode (normal or idempotent).
@@ -110,7 +110,7 @@ public interface ObjectPrx
      * @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
+     * contains the encoded user exception. If the operation raises a run-time exception,
      * it throws it directly.
      *
      * @see Blobject
@@ -119,7 +119,7 @@ public interface ObjectPrx
     boolean ice_invoke(String operation, OperationMode mode, byte[] inParams, ByteSeqHolder outParams);
 
     /**
-     * Invoke an operation dynamically.
+     * Invokes an operation dynamically.
      *
      * @param operation The name of the operation to invoke.
      * @param mode The operation mode (normal or idempotent).
@@ -147,7 +147,7 @@ public interface ObjectPrx
      * @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
+     * contains the encoded user exception. If the operation raises a run-time exception,
      * it throws it directly.
      *
      * @see AMI_Object_ice_invoke
@@ -162,11 +162,11 @@ public interface ObjectPrx
      * @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.
      * @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
+     * contains the encoded user exception. If the operation raises a run-time exception,
      * it throws it directly.
      *
      * @see AMI_Object_ice_invoke
@@ -316,16 +316,17 @@ public interface ObjectPrx
     /**
      * Returns whether this proxy uses only secure endpoints.
      *
-     * @return <code>true</code> if all endpoints for this proxy are secure; <code>false</code>, otherwise.
+     * @return <code>True</code> if this proxy communicates only via secure endpoints; <code>false</code>, otherwise.
      **/
     boolean ice_isSecure();
 
     /**
-     * Creates a new proxy that is identical to this proxy, except for its endpoints.
+     * Creates a new proxy that is identical to this proxy, except for how it selects 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
+     * @param b If <code>b</code> is <code>true</code>, only endpoints that use a secure transport are
+     * used by the new proxy. If <code>b</code> is false, the returned proxy uses both secure and insecure
+     * endpoints.
+     * @return The new proxy with the specified selection policy.
      **/
     ObjectPrx ice_secure(boolean b);
 
@@ -333,7 +334,7 @@ public interface ObjectPrx
      * 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;
+     * attempts to use insecure endpoints; <code>false</code>, otherwise.
      **/
     boolean ice_isPreferSecure();
 
@@ -373,7 +374,7 @@ public interface ObjectPrx
     /**
      * 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.
      **/
     ObjectPrx ice_locator(Ice.LocatorPrx locator);
diff --git a/java/src/Ice/ObjectPrxHelper.java b/java/src/Ice/ObjectPrxHelper.java
index da4360fe5ff..cb7a5f40edb 100644
--- a/java/src/Ice/ObjectPrxHelper.java
+++ b/java/src/Ice/ObjectPrxHelper.java
@@ -9,6 +9,9 @@
 
 package Ice;
 
+/**
+ * Base class for all proxy helpers.
+ **/
 public class ObjectPrxHelper extends ObjectPrxHelperBase
 {
     /**
diff --git a/java/src/Ice/ObjectPrxHelperBase.java b/java/src/Ice/ObjectPrxHelperBase.java
index 87978423164..213194f20bd 100644
--- a/java/src/Ice/ObjectPrxHelperBase.java
+++ b/java/src/Ice/ObjectPrxHelperBase.java
@@ -170,8 +170,8 @@ 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>.
+     * @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>.
      **/
     public final String[]
     ice_ids()
@@ -183,8 +183,8 @@ public class ObjectPrxHelperBase implements ObjectPrx, java.io.Serializable
      * 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>.
+     * @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>.
      **/
     public final String[]
     ice_ids(java.util.Map<String, String> __context)
diff --git a/java/src/Ice/OutputStream.java b/java/src/Ice/OutputStream.java
index 654cbcb0b64..0fce2ae23b6 100644
--- a/java/src/Ice/OutputStream.java
+++ b/java/src/Ice/OutputStream.java
@@ -18,7 +18,7 @@ package Ice;
 public interface OutputStream
 {
     /**
-     * Returns the communicator for this input stream.
+     * Returns the communicator for this output stream.
      *
      * @return The communicator.
      **/
@@ -54,6 +54,11 @@ public interface OutputStream
      **/
     void writeByteSeq(byte[] v);
 
+    /**
+     * Writes a serializable Java object to the stream.
+     *
+     * @param o The serializable object to write.
+     **/
     void writeSerializable(java.io.Serializable o);
 
     /**
@@ -212,7 +217,7 @@ public interface OutputStream
     /**
      * Indicates that marshaling of a request or reply is finished.
      *
-     * @return The byte sequence containing the encode request or reply.
+     * @return The byte sequence containing the encoded request or reply.
      **/
     byte[] finished();
 
diff --git a/java/src/Ice/ThreadNotification.java b/java/src/Ice/ThreadNotification.java
index 41b687f8f14..1b7aed342b3 100644
--- a/java/src/Ice/ThreadNotification.java
+++ b/java/src/Ice/ThreadNotification.java
@@ -21,7 +21,7 @@ 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.
+     * thread it creates. The call is made by the newly-started thread.
      **/
     void start();
 
diff --git a/java/src/Ice/Util.java b/java/src/Ice/Util.java
index 1e07bc26296..064dd607257 100644
--- a/java/src/Ice/Util.java
+++ b/java/src/Ice/Util.java
@@ -9,6 +9,9 @@
 
 package Ice;
 
+/**
+ * Utility methods for the Ice run time.
+ **/
 public final class Util
 {
     /**
@@ -456,7 +459,7 @@ public final class Util
     /**
      * Returns the process-wide logger.
      *
-     * The process-wide logger.
+     * @return The process-wide logger.
      **/
     public static Logger
     getProcessLogger()
@@ -478,7 +481,7 @@ public final class Util
     /**
      * Changes the process-wide logger.
      *
-     * @param The new process-wide logger.
+     * @param logger The new process-wide logger.
      **/
     public static void
     setProcessLogger(Logger logger)
@@ -490,7 +493,7 @@ public final class Util
     }
 
     /**
-     * Returns the Ice version in the form <code>A.B.C,</code>, where <code>A</code> indicates the
+     * 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.
      *
diff --git a/java/src/IceSSL/PluginFactory.java b/java/src/IceSSL/PluginFactory.java
index 70ada47f651..7d8f1d7993f 100644
--- a/java/src/IceSSL/PluginFactory.java
+++ b/java/src/IceSSL/PluginFactory.java
@@ -22,7 +22,7 @@ public class PluginFactory implements Ice.PluginFactory
      * @param args The arguments that are specified in the plug-in's configuration.
      *
      * @return The new plug-in. <code>null</code> can be returned to indicate
-     * that a general error occurred. Alterntively, <code>create</code> can throw
+     * that a general error occurred. Alternatively, <code>create</code> can throw
      * {@link PluginInitializationException} to provide more detailed information.
      **/
     public Ice.Plugin