Lots of javadoc comments.

1 files changed, 170 insertions, 0 deletions

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();
 }