Merge pull request #396 from msgpack/javadoc-1

Adding JavaDoc

Author: xerial

msgpack-core/src/main/java/org/msgpack/core/MessageBufferPacker.java

@@ -23,7 +23,11 @@
 import java.util.List;
 
 /**
- * MessagePacker that is useful to produce byte array output
+ * MessagePacker that is useful to produce byte array output.
+ * <p>
+ * This class allocates a new buffer instead of resizing the buffer when data doesn't fit in the initial capacity.
+ * This is faster than ByteArrayOutputStream especially when size of written bytes is large because resizing a buffer
+ * usually needs to copy contents of the buffer.
  */
 public class MessageBufferPacker
         extends MessagePacker
@@ -52,42 +56,69 @@ private ArrayBufferOutput getArrayBufferOut()
         return (ArrayBufferOutput) out;
     }
 
+    /**
+     * Clears the written data.
+     */
     public void clear()
     {
         getArrayBufferOut().clear();
     }
 
+    /**
+     * Gets copy of the written data as a byte array.
+     * <p>
+     * If your application needs better performance and smaller memory consumption, you may prefer
+     * {@link #toMessageBuffer()} or {@link #toBufferList()} to avoid copying.
+     *
+     * @return the byte array
+     */
     public byte[] toByteArray()
     {
         try {
             flush();
         }
         catch (IOException ex) {
-            // IOException must not happen because underlaying ArrayBufferOutput never throws IOException
+            // IOException must not happen because underlying ArrayBufferOutput never throws IOException
             throw new RuntimeException(ex);
         }
         return getArrayBufferOut().toByteArray();
     }
 
+    /**
+     * Gets the written data as a MessageBuffer.
+     * <p>
+     * Unlike {@link #toByteArray()}, this method omits copy of the contents if size of the written data is smaller
+     * than a single buffer capacity.
+     *
+     * @return the MessageBuffer instance
+     */
     public MessageBuffer toMessageBuffer()
     {
         try {
             flush();
         }
         catch (IOException ex) {
-            // IOException must not happen because underlaying ArrayBufferOutput never throws IOException
+            // IOException must not happen because underlying ArrayBufferOutput never throws IOException
             throw new RuntimeException(ex);
         }
         return getArrayBufferOut().toMessageBuffer();
     }
 
+    /**
+     * Returns the written data as a list of MessageBuffer.
+     * <p>
+     * Unlike {@link #toByteArray()} or {@link #toMessageBuffer()}, this is the fastest method that doesn't
+     * copy contents in any cases.
+     *
+     * @return the list of MessageBuffer instances
+     */
     public List<MessageBuffer> toBufferList()
     {
         try {
             flush();
         }
         catch (IOException ex) {
-            // IOException must not happen because underlaying ArrayBufferOutput never throws IOException
+            // IOException must not happen because underlying ArrayBufferOutput never throws IOException
             throw new RuntimeException(ex);
         }
         return getArrayBufferOut().toBufferList();

msgpack-core/src/main/java/org/msgpack/core/MessageInsufficientBufferException.java

@@ -15,6 +15,9 @@
 //
 package org.msgpack.core;
 
+/**
+ * Exception that indicates end of input.
+ */
 public class MessageInsufficientBufferException
         extends MessagePackException
 {