JavaDoc for I/O classes.

guacamole-common/src/main/java/net/sourceforge/guacamole/io/GuacamoleReader.java

@@ -22,9 +22,37 @@ import net.sourceforge.guacamole.protocol.GuacamoleInstruction;
  *  along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
+/**
+ * Provides abstract and raw character read access to a stream of Guacamole
+ * instructions.
+ *
+ * @author Michael Jumper
+ */
 public interface GuacamoleReader {
 
+    /**
+     * Reads at least one complete Guacamole instruction, returning a buffer
+     * containing one or more complete Guacamole instructions and no
+     * incomplete Guacamole instructions. This function will block until at
+     * least one complete instruction is available.
+     *
+     * @return A buffer containing at least one complete Guacamole instruction,
+     *         or null if no more instructions are available for reading.
+     * @throws GuacamoleException If an error occurs while reading from the
+     *                            stream.
+     */
     public char[] read() throws GuacamoleException;
+
+    /**
+     * Reads exactly one complete Guacamole instruction and returns the fully
+     * parsed instruction.
+     *
+     * @return The next complete instruction from the stream, fully parsed, or
+     *         null if no more instructions are available for reading.
+     * @throws GuacamoleException If an error occurs while reading from the
+     *                            stream, or if the instruction cannot be
+     *                            parsed.
+     */
     public GuacamoleInstruction readInstruction() throws GuacamoleException;
 
 }

guacamole-common/src/main/java/net/sourceforge/guacamole/io/GuacamoleWriter.java

@@ -22,10 +22,46 @@ import net.sourceforge.guacamole.protocol.GuacamoleInstruction;
  *  along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
+/**
+ * Provides abstract and raw character write access to a stream of Guacamole
+ * instructions.
+ *
+ * @author Michael Jumper
+ */
 public interface GuacamoleWriter {
 
+    /**
+     * Writes a portion of the given array of characters to the Guacamole
+     * instruction stream. The portion must contain only complete Guacamole
+     * instructions.
+     *
+     * @param chunk An array of characters containing Guacamole instructions.
+     * @param off The start offset of the portion of the array to write.
+     * @param len The length of the portion of the array to write.
+     * @throws GuacamoleException If an error occurred while writing the
+     *                            portion of the array specified.
+     */
     public void write(char[] chunk, int off, int len) throws GuacamoleException;
+
+    /**
+     * Writes the entire given array of characters to the Guacamole instruction
+     * stream. The array must consist only of complete Guacamole instructions.
+     *
+     * @param chunk An array of characters consisting only of complete
+     *              Guacamole instructions.
+     * @throws GuacamoleException If an error occurred while writing the
+     *                            the specified array.
+     */
     public void write(char[] chunk) throws GuacamoleException;
+
+    /**
+     * Writes the given fully parsed instruction to the Guacamole instruction
+     * stream.
+     *
+     * @param instruction The Guacamole instruction to write.
+     * @throws GuacamoleException If an error occurred while writing the
+     *                            instruction.
+     */
     public void writeInstruction(GuacamoleInstruction instruction) throws GuacamoleException;
 
 }

guacamole-common/src/main/java/net/sourceforge/guacamole/io/ReaderGuacamoleReader.java

@@ -25,10 +25,22 @@ import net.sourceforge.guacamole.protocol.GuacamoleInstruction.Operation;
  *  along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
+/**
+ * A GuacamoleReader which wraps a standard Java Reader, using that Reader as
+ * the Guacamole instruction stream.
+ *
+ * @author Michael Jumper
+ */
 public class ReaderGuacamoleReader implements GuacamoleReader {
 
     private Reader input;
 
+    /**
+     * Creates a new ReaderGuacamoleReader which will use the given Reader as
+     * the Guacamole instruction stream.
+     *
+     * @param input The Reader to use as the Guacamole instruction stream.
+     */
     public ReaderGuacamoleReader(Reader input) {
         this.input = input;
     }

guacamole-common/src/main/java/net/sourceforge/guacamole/io/WriterGuacamoleWriter.java

@@ -24,10 +24,22 @@ import net.sourceforge.guacamole.protocol.GuacamoleInstruction;
  *  along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
+/**
+ * A GuacamoleWriter which wraps a standard Java Writer, using that Writer as
+ * the Guacamole instruction stream.
+ *
+ * @author Michael Jumper
+ */
 public class WriterGuacamoleWriter implements GuacamoleWriter {
 
     private Writer output;
 
+    /**
+     * Creates a new WriterGuacamoleWriter which will use the given Writer as
+     * the Guacamole instruction stream.
+     *
+     * @param output The Writer to use as the Guacamole instruction stream.
+     */
     public WriterGuacamoleWriter(Writer output) {
         this.output = output;
     }