bug 4623 - missing doc comments

9 files changed, 149 insertions, 2 deletions

diff --git a/java/src/Ice/AMDCallback.java b/java/src/Ice/AMDCallback.java
index be31358faef..f77f2cdaf7e 100644
--- a/java/src/Ice/AMDCallback.java
+++ b/java/src/Ice/AMDCallback.java
@@ -9,6 +9,9 @@
 
 package Ice;
 
+/**
+ * AMDCallback is the interface from which all AMD callbacks are derived.
+ **/
 public interface AMDCallback
 {
     /**
diff --git a/java/src/Ice/AsyncResult.java b/java/src/Ice/AsyncResult.java
index 4263f3e1c9c..6655b51b977 100644
--- a/java/src/Ice/AsyncResult.java
+++ b/java/src/Ice/AsyncResult.java
@@ -9,6 +9,11 @@
 
 package Ice;
 
+/**
+ * An AsyncResult object is the return value of an asynchronous invocation.
+ * With this object, an application can obtain several attributes of the
+ * invocation and discover its outcome.
+ **/
 public class AsyncResult
 {
     protected AsyncResult(IceInternal.Instance instance, String op, IceInternal.CallbackBase del)
@@ -22,21 +27,42 @@ public class AsyncResult
         _callback = del;
     }
 
+    /**
+     * Returns the communicator that sent the invocation.
+     *
+     * @return The communicator.
+     **/
     public Communicator getCommunicator()
     {
         return null;
     }
 
+    /**
+     * Returns the connection that that was used for the invocation.
+     *
+     * @return The connection.
+     **/
     public Connection getConnection()
     {
         return null;
     }
 
+    /**
+     * Returns the proxy that that was used to call the <code>begin_</code> method.
+     *
+     * @return The proxy.
+     **/
     public ObjectPrx getProxy()
     {
         return null;
     }
 
+    /**
+     * Indicates whether the result of an invocation is available.
+     *
+     * @return True if the result is available, which means a call to the <code>end_</code>
+     * method will not block. The method returns false if the result is not yet available.
+     **/
     public final boolean isCompleted()
     {
         synchronized(_monitor)
@@ -45,6 +71,9 @@ public class AsyncResult
         }
     }
 
+    /**
+     * Blocks the caller until the result of the invocation is available.
+     **/
     public final void waitForCompleted()
     {
         synchronized(_monitor)
@@ -62,6 +91,17 @@ public class AsyncResult
         }
     }
 
+    /**
+     * When you call the <code>begin_</code> method, the Ice run time attempts to
+     * write the corresponding request to the client-side transport. If the
+     * transport cannot accept the request, the Ice run time queues the request
+     * for later transmission. This method returns true if, at the time it is called,
+     * the request has been written to the local transport (whether it was initially
+     * queued or not). Otherwise, if the request is still queued, this method returns
+     * false.
+     *
+     * @return True if the request has been sent, or false if the request is queued.
+     **/
     public final boolean isSent()
     {
         synchronized(_monitor)
@@ -70,6 +110,9 @@ public class AsyncResult
         }
     }
 
+    /**
+     * Blocks the caller until the request has been written to the client-side transport.
+     **/
     public final void waitForSent()
     {
         synchronized(_monitor)
@@ -87,11 +130,25 @@ public class AsyncResult
         }
     }
 
+    /**
+     * This method returns true if a request was written to the client-side
+     * transport without first being queued. If the request was initially
+     * queued, this method returns false (independent of whether the request
+     * is still in the queue or has since been written to the client-side transport).
+     *
+     * @return True if the request was sent without being queued, or false
+     * otherwise.
+     **/
     public final boolean sentSynchronously()
     {
         return _sentSynchronously; // No lock needed, immutable once __send() is called
     }
 
+    /**
+     * Returns the name of the operation.
+     *
+     * @return The operation name.
+     **/
     public final String getOperation()
     {
         return _operation;
diff --git a/java/src/Ice/BlobjectAsync.java b/java/src/Ice/BlobjectAsync.java
index 38c88998456..6f05157397a 100644
--- a/java/src/Ice/BlobjectAsync.java
+++ b/java/src/Ice/BlobjectAsync.java
@@ -9,8 +9,25 @@
 
 package Ice;
 
+/**
+ * <code>BlobjectAsync</code> is the base class for asynchronous dynamic
+ * dispatch servants. A server application derives a concrete servant
+ * class that implements the {@link BlobjectAsync#ice_invoke_async} method,
+ * which is called by the Ice run time to deliver every request on this
+ * object.
+ **/
 public abstract class BlobjectAsync extends Ice.ObjectImpl
 {
+    /**
+     * Dispatch an incoming request.
+     *
+     * @param cb The callback object through which the invocation's results
+     * must be delivered.
+     * @param inParams The encoded input parameters.
+     * @param current The Current object, which provides important information
+     * about the request, such as the identity of the target object and the
+     * name of the operation.
+     **/
     public abstract void
     ice_invoke_async(AMD_Object_ice_invoke cb, byte[] inParams, Current current);
 
diff --git a/java/src/Ice/DispatchInterceptorAsyncCallback.java b/java/src/Ice/DispatchInterceptorAsyncCallback.java
index f37851b3f50..fdbf42ebe06 100644
--- a/java/src/Ice/DispatchInterceptorAsyncCallback.java
+++ b/java/src/Ice/DispatchInterceptorAsyncCallback.java
@@ -6,8 +6,30 @@
 
 package Ice;
 
+/**
+ * The callback object for asynchronous dispatch.
+ **/
 public interface DispatchInterceptorAsyncCallback
 {
+    /**
+     * Called when the operation succeeded or raised a user exception,
+     * as indicated by the <code>ok</code> parameter.
+     *
+     * @param ok True if the operation succeeded, or false if the
+     * operation raised a user exception.
+     * @return True to allow the Ice run time to handle the result
+     * as it normally would, or false if the interceptor has handled
+     * the operation.
+     **/
     boolean response(boolean ok);
+
+    /**
+     * Called when the operation failed with a run-time exception.
+     *
+     * @param ex The exception raised by the operation.
+     * @return True to allow the Ice run time to handle the result
+     * as it normally would, or false if the interceptor has handled
+     * the operation.
+     **/
     boolean exception(java.lang.Exception ex);
 }
diff --git a/java/src/Ice/Dispatcher.java b/java/src/Ice/Dispatcher.java
index 9c3b2107341..cb5e5e81d99 100644
--- a/java/src/Ice/Dispatcher.java
+++ b/java/src/Ice/Dispatcher.java
@@ -9,7 +9,26 @@
 
 package Ice;
 
+/**
+ * You can control which thread receives operation invocations and AMI
+ * callbacks by implementing the <code>Dispatcher</code> interface and
+ * supplying an instance in <code>InitializationData</code> when
+ * initializing a communicator.
+ * <p>
+ * For example, you can use this dispatching facility to ensure that
+ * all invocations and callbacks are dispatched in a GUI event loop
+ * thread so that it is safe to invoke directly on GUI objects.
+ **/
 public interface Dispatcher
 {
+    /**
+     * Responsible for dispatching an invocation or AMI callback.
+     * The method must eventually invoke <code>run</code> on the
+     * supplied <code>Runnable</code> object.
+     *
+     * @param runnable The object encapsulating the invocation or
+     * callback to be dispatched.
+     * @param con The connection associated with the dispatch.
+     **/
     void dispatch(Runnable runnable, Ice.Connection con);
 }
diff --git a/java/src/Ice/DoubleHolder.java b/java/src/Ice/DoubleHolder.java
index cb77acb04e9..08fc2233244 100644
--- a/java/src/Ice/DoubleHolder.java
+++ b/java/src/Ice/DoubleHolder.java
@@ -9,10 +9,10 @@
 
 package Ice;
 
-public final class DoubleHolder
 /**
  * Holder class for doubles that are out- or inout-parameters.
  **/
+public final class DoubleHolder
 {
     /**
      * Instantiates the class with the value zero.
diff --git a/java/src/Ice/LocalObjectHolder.java b/java/src/Ice/LocalObjectHolder.java
index b7e69677a81..ea91b57b1dc 100644
--- a/java/src/Ice/LocalObjectHolder.java
+++ b/java/src/Ice/LocalObjectHolder.java
@@ -9,13 +9,22 @@
 
 package Ice;
 
+/**
+ * Holder class for local objects that are out- or inout-parameters.
+ **/
 public final class LocalObjectHolder
 {
+    /**
+     * Instantiates the class with a <code>null</code> value.
+     **/
     public
     LocalObjectHolder()
     {
     }
 
+    /**
+     * Instantiates the class with the passed local object.
+     **/
     public
     LocalObjectHolder(java.lang.Object value)
     {
diff --git a/java/src/Ice/Object.java b/java/src/Ice/Object.java
index 93382312fe2..054da15ed61 100644
--- a/java/src/Ice/Object.java
+++ b/java/src/Ice/Object.java
@@ -136,7 +136,7 @@ public interface Object
      * 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
+     * @param cb The callback object for asynchronous dispatch. For synchronous dispatch, the callback object
      * must be <code>null</code>.
      * @return The dispatch status for the operation.
      *
diff --git a/java/src/Ice/UserExceptionWriter.java b/java/src/Ice/UserExceptionWriter.java
index 71bc31b6727..67cf201d5ec 100644
--- a/java/src/Ice/UserExceptionWriter.java
+++ b/java/src/Ice/UserExceptionWriter.java
@@ -9,16 +9,36 @@
 
 package Ice;
 
+/**
+ * Allows a Dynamic Ice application to wrap a native exception and
+ * intercept its marshaling.
+ *
+ * @see OutputStream
+ **/
 public abstract class UserExceptionWriter extends UserException
 {
+    /**
+     * Creates a writer for the given communicator.
+     **/
     public UserExceptionWriter(Communicator communicator)
     {
         _communicator = communicator;
     }
 
+    /**
+     * Marshal the encapsulated exception into an output stream.
+     *
+     * @param os The output stream.
+     **/
     public abstract void
     write(Ice.OutputStream os);
 
+    /**
+     * Indicates whether the encapsulated exception contains one or more
+     * data members that are instances of Slice classes.
+     *
+     * @return True if the exception contains classes, or false otherwise.
+     **/
     public abstract boolean
     usesClasses();