From 5228c5c31e670b86bca3745a5986fedca133de4a Mon Sep 17 00:00:00 2001 From: Sadayuki Furuhashi Date: Tue, 18 Oct 2016 20:48:59 -0700 Subject: [PATCH 1/5] Adding JavaDoc - part 1 --- .../MessageInsufficientBufferException.java | 3 + .../java/org/msgpack/core/MessagePack.java | 249 +++++++++---- .../java/org/msgpack/core/MessagePacker.java | 297 ++++++++++++++-- .../org/msgpack/core/MessageUnpacker.java | 334 ++++++++++++++++-- 4 files changed, 746 insertions(+), 137 deletions(-) diff --git a/msgpack-core/src/main/java/org/msgpack/core/MessageInsufficientBufferException.java b/msgpack-core/src/main/java/org/msgpack/core/MessageInsufficientBufferException.java index 838dc77ab..099dcac6f 100644 --- a/msgpack-core/src/main/java/org/msgpack/core/MessageInsufficientBufferException.java +++ b/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 { diff --git a/msgpack-core/src/main/java/org/msgpack/core/MessagePack.java b/msgpack-core/src/main/java/org/msgpack/core/MessagePack.java index 7737aa664..2c84d2328 100644 --- a/msgpack-core/src/main/java/org/msgpack/core/MessagePack.java +++ b/msgpack-core/src/main/java/org/msgpack/core/MessagePack.java @@ -33,20 +33,54 @@ import java.nio.charset.CodingErrorAction; /** - * This class has MessagePack prefix code definitions and packer/unpacker factory methods. + * Convenience class to build packer and unpacker classes. + * + * You may choose factory method as following + * + *

+ * Deserializing objects from binary: + * + * + * + * + * + * + * + * + *
Input typeFactory methodReturn type
byte[]{@link #newDefaultUnpacker(byte[], int, int)}{@link MessageUnpacker}
ByteBuffer{@link #newDefaultUnpacker(ByteBuffer)}{@link MessageUnpacker}
InputStream{@link #newDefaultUnpacker(InputStream)}{@link MessageUnpacker}
ReadableByteChannel{@link #newDefaultUnpacker(ReadableByteChannel)}{@link MessageUnpacker}
{@link org.msgpack.core.buffer.MessageBufferInput}{@link #newDefaultUnpacker(MessageBufferInput)}{@link MessageUnpacker}
+ * + *

+ * Serializing objects into binary: + * + * + * + * + * + * + * + *
Output typeFactory methodReturn type
byte[]{@link #newDefaultBufferPacker()}{@link MessageBufferPacker}
OutputStream{@link #newDefaultPacker(OutputStream)}{@link MessagePacker}
WritableByteChannel{@link #newDefaultPacker(WritableByteChannel)}{@link MessagePacker}
{@link org.msgpack.core.buffer.MessageBufferOutput}{@link #newDefaultPacker(MessageBufferOutput)}{@link MessagePacker}
+ * */ public class MessagePack { + /** + * @exclude + * Applications should use java.nio.charset.StandardCharsets.UTF_8 instead since Java 7. + */ public static final Charset UTF8 = Charset.forName("UTF-8"); /** - * Default packer/unpacker configurations + * Configuration of a {@link MessagePacker} created by {@link #newDefaultPacker(MessageBufferOutput)} and {@link #newDefaultBufferPacker()} methods. */ public static final PackerConfig DEFAULT_PACKER_CONFIG = new PackerConfig(); + + /** + * Configuration of a {@link MessageUnpacker} created by {@link #newDefaultUnpacker(MessageBufferInput)} methods. + */ public static final UnpackerConfig DEFAULT_UNPACKER_CONFIG = new UnpackerConfig(); /** - * The prefix code set of MessagePack. See also https://github.com/msgpack/msgpack/blob/master/spec.md for details. + * The prefix code set of MessagePack format. See also https://github.com/msgpack/msgpack/blob/master/spec.md for details. */ public static final class Code { @@ -139,10 +173,16 @@ private MessagePack() } /** - * Create a packer that outputs the packed data to the specified output + * Creates a packer that serializes objects into the specified output. + *

+ * {@link org.msgpack.core.buffer.MessageBufferOutput} is an interface that lets applications customize memory + * allocation of internal buffer of {@link MessagePacker}. You may prefer {@link #newDefaultBufferPacker()}, + * {@link #newDefaultPacker(OutputStream)}, or {@link #newDefaultPacker(WritableByteChannel)} methods instead. + *

+ * This method is equivalent to DEFAULT_PACKER_CONFIG.newPacker(out). * - * @param out - * @return + * @param out A MessageBufferOutput that allocates buffer chunks and receives the buffer chunks with packed data filled in them + * @return A new MessagePacker instance */ public static MessagePacker newDefaultPacker(MessageBufferOutput out) { @@ -150,10 +190,15 @@ public static MessagePacker newDefaultPacker(MessageBufferOutput out) } /** - * Create a packer that outputs the packed data to a target output stream + * Creates a packer that serializes objects into the specified output stream. + *

+ * Note that you don't have to wrap OutputStream in BufferedOutputStream because MessagePacker has buffering + * internally. + *

+ * This method is equivalent to DEFAULT_PACKER_CONFIG.newPacker(out). * - * @param out - * @return + * @param out The output stream that receives sequence of bytes + * @return A new MessagePacker instance */ public static MessagePacker newDefaultPacker(OutputStream out) { @@ -161,10 +206,12 @@ public static MessagePacker newDefaultPacker(OutputStream out) } /** - * Create a packer that outputs the packed data to a channel + * Creates a packer that serializes objects into the specified writable channel. + *

+ * This method is equivalent to DEFAULT_PACKER_CONFIG.newPacker(channel). * - * @param channel - * @return + * @param channel The output channel that receives sequence of bytes + * @return A new MessagePacker instance */ public static MessagePacker newDefaultPacker(WritableByteChannel channel) { @@ -172,9 +219,13 @@ public static MessagePacker newDefaultPacker(WritableByteChannel channel) } /** - * Create a packer for storing packed data into a byte array + * Creates a packer that serializes objects into byte arrays. + *

+ * This method provides an optimized implementation of newDefaultBufferPacker(new ByteArrayOutputStream()). + * + * This method is equivalent to DEFAULT_PACKER_CONFIG.newBufferPacker(). * - * @return + * @return A new MessageBufferPacker instance */ public static MessageBufferPacker newDefaultBufferPacker() { @@ -182,10 +233,17 @@ public static MessageBufferPacker newDefaultBufferPacker() } /** - * Create an unpacker that reads the data from a given input + * Creates an unpacker that deserializes objects from a specified input. + *

+ * {@link org.msgpack.core.buffer.MessageBufferInput} is an interface that lets applications customize memory + * allocation of internal buffer of {@link MessageUnpacker}. You may prefer + * {@link #newDefaultUnpacker(InputStream)}, {@link #newDefaultUnpacker(ReadableByteChannel)}, + * {@link #newDefaultUnpacker(byte[], int, int)}, or {@link #newDefaultUnpacker(ByteBuffer)} methods instead. + *

+ * This method is equivalent to DEFAULT_UNPACKER_CONFIG.newDefaultUnpacker(in). * - * @param in - * @return + * @param in The input stream that provides sequence of buffer chunks and optionally reuses them when MessageUnpacker consumed one completely + * @return A new MessageUnpacker instance */ public static MessageUnpacker newDefaultUnpacker(MessageBufferInput in) { @@ -193,10 +251,15 @@ public static MessageUnpacker newDefaultUnpacker(MessageBufferInput in) } /** - * Create an unpacker that reads the data from a given input stream + * Creates an unpacker that deserializes objects from a specified input stream. + *

+ * Note that you don't have to wrap InputStream in BufferedInputStream because MessageUnpacker has buffering + * internally. + *

+ * This method is equivalent to DEFAULT_UNPACKER_CONFIG.newDefaultUnpacker(in). * - * @param in - * @return + * @param in The input stream that provides sequence of bytes + * @return A new MessageUnpacker instance */ public static MessageUnpacker newDefaultUnpacker(InputStream in) { @@ -204,10 +267,12 @@ public static MessageUnpacker newDefaultUnpacker(InputStream in) } /** - * Create an unpacker that reads the data from a given channel + * Creates an unpacker that deserializes objects from a specified readable channel. + *

+ * This method is equivalent to DEFAULT_UNPACKER_CONFIG.newDefaultUnpacker(in). * - * @param channel - * @return + * @param channel The input channel that provides sequence of bytes + * @return A new MessageUnpacker instance */ public static MessageUnpacker newDefaultUnpacker(ReadableByteChannel channel) { @@ -215,10 +280,14 @@ public static MessageUnpacker newDefaultUnpacker(ReadableByteChannel channel) } /** - * Create an unpacker that reads the data from a given byte array + * Creates an unpacker that deserializes objects from a specified byte array. + *

+ * This method provides an optimized implementation of newDefaultUnpacker(new ByteArrayInputStream(contents)). + *

+ * This method is equivalent to DEFAULT_UNPACKER_CONFIG.newDefaultUnpacker(contents). * - * @param contents - * @return + * @param contents The byte array that contains packed objects in MessagePack format + * @return A new MessageUnpacker instance that will never throw IOException */ public static MessageUnpacker newDefaultUnpacker(byte[] contents) { @@ -226,12 +295,16 @@ public static MessageUnpacker newDefaultUnpacker(byte[] contents) } /** - * Create an unpacker that reads the data from a given byte array [offset, offset+length) + * Creates an unpacker that deserializes objects from subarray of a specified byte array. + *

+ * This method provides an optimized implementation of newDefaultUnpacker(new ByteArrayInputStream(contents, offset, length)). + *

+ * This method is equivalent to DEFAULT_UNPACKER_CONFIG.newDefaultUnpacker(contents). * - * @param contents - * @param offset - * @param length - * @return + * @param contents The byte array that contains packed objects + * @param offset The index of the first byte + * @param length The number of bytes + * @return A new MessageUnpacker instance that will never throw IOException */ public static MessageUnpacker newDefaultUnpacker(byte[] contents, int offset, int length) { @@ -239,10 +312,16 @@ public static MessageUnpacker newDefaultUnpacker(byte[] contents, int offset, in } /** - * Create an unpacker that reads the data from a given ByteBuffer + * Creates an unpacker that deserializes objects from a specified ByteBuffer. + *

+ * Note that the returned unpacker reads data from the current position of the ByteBuffer until its limit. + * However, its position does not change when unpacker reads data. You may use + * {@link MessageUnpacker#getTotalReadBytes()} to get actual amount of bytes used in ByteBuffer. + *

+ * This method supports both non-direct buffer and direct buffer. * - * @param contents - * @return + * @param contents The byte buffer that contains packed objects + * @return A new MessageUnpacker instance that will never throw IOException */ public static MessageUnpacker newDefaultUnpacker(ByteBuffer contents) { @@ -305,10 +384,13 @@ public boolean equals(Object obj) } /** - * Create a packer that outputs the packed data to a given output + * Creates a packer that serializes objects into the specified output. + *

+ * {@link org.msgpack.core.buffer.MessageBufferOutput} is an interface that lets applications customize memory + * allocation of internal buffer of {@link MessagePacker}. * - * @param out - * @return + * @param out A MessageBufferOutput that allocates buffer chunks and receives the buffer chunks with packed data filled in them + * @return A new MessagePacker instance */ public MessagePacker newPacker(MessageBufferOutput out) { @@ -316,10 +398,13 @@ public MessagePacker newPacker(MessageBufferOutput out) } /** - * Create a packer that outputs the packed data to a given output stream + * Creates a packer that serializes objects into the specified output stream. + *

+ * Note that you don't have to wrap OutputStream in BufferedOutputStream because MessagePacker has buffering + * internally. * - * @param out - * @return + * @param out The output stream that receives sequence of bytes + * @return A new MessagePacker instance */ public MessagePacker newPacker(OutputStream out) { @@ -327,10 +412,10 @@ public MessagePacker newPacker(OutputStream out) } /** - * Create a packer that outputs the packed data to a given output channel + * Creates a packer that serializes objects into the specified writable channel. * - * @param channel - * @return + * @param channel The output channel that receives sequence of bytes + * @return A new MessagePacker instance */ public MessagePacker newPacker(WritableByteChannel channel) { @@ -338,9 +423,11 @@ public MessagePacker newPacker(WritableByteChannel channel) } /** - * Create a packer for storing packed data into a byte array + * Creates a packer that serializes objects into byte arrays. + *

+ * This method provides an optimized implementation of newDefaultBufferPacker(new ByteArrayOutputStream()). * - * @return + * @return A new MessageBufferPacker instance */ public MessageBufferPacker newBufferPacker() { @@ -348,13 +435,13 @@ public MessageBufferPacker newBufferPacker() } /** - * Use String.getBytes() for converting Java Strings that are smaller than this threshold into UTF8. + * Use String.getBytes() for converting Java Strings that are shorter than this threshold. * Note that this parameter is subject to change. */ - public PackerConfig withSmallStringOptimizationThreshold(int bytes) + public PackerConfig withSmallStringOptimizationThreshold(int length) { PackerConfig copy = clone(); - copy.smallStringOptimizationThreshold = bytes; + copy.smallStringOptimizationThreshold = length; return copy; } @@ -364,8 +451,8 @@ public int getSmallStringOptimizationThreshold() } /** - * When the next payload size exceeds this threshold, MessagePacker will call MessageBufferOutput.flush() before - * packing the data (default: 8192). + * When the next payload size exceeds this threshold, MessagePacker will call + * {@link org.msgpack.core.buffer.MessageBufferOutput#flush()} before writing more data (default: 8192). */ public PackerConfig withBufferFlushThreshold(int bytes) { @@ -380,7 +467,7 @@ public int getBufferFlushThreshold() } /** - * When a packer is created with newPacker(OutputStream) or newPacker(WritableByteChannel), the stream will be + * When a packer is created with {@link #newPacker(OutputStream)} or {@link #newPacker(WritableByteChannel)}, the stream will be * buffered with this size of buffer (default: 8192). */ public PackerConfig withBufferSize(int bytes) @@ -483,10 +570,13 @@ public boolean equals(Object obj) } /** - * Create an unpacker that reads the data from a given input + * Creates an unpacker that deserializes objects from a specified input. + *

+ * {@link org.msgpack.core.buffer.MessageBufferInput} is an interface that lets applications customize memory + * allocation of internal buffer of {@link MessageUnpacker}. * - * @param in - * @return + * @param in The input stream that provides sequence of buffer chunks and optionally reuses them when MessageUnpacker consumed one completely + * @return A new MessageUnpacker instance */ public MessageUnpacker newUnpacker(MessageBufferInput in) { @@ -494,10 +584,13 @@ public MessageUnpacker newUnpacker(MessageBufferInput in) } /** - * Create an unpacker that reads the data from a given input stream + * Creates an unpacker that deserializes objects from a specified input stream. + *

+ * Note that you don't have to wrap InputStream in BufferedInputStream because MessageUnpacker has buffering + * internally. * - * @param in - * @return + * @param in The input stream that provides sequence of bytes + * @return A new MessageUnpacker instance */ public MessageUnpacker newUnpacker(InputStream in) { @@ -505,10 +598,10 @@ public MessageUnpacker newUnpacker(InputStream in) } /** - * Create an unpacker that reads the data from a given channel + * Creates an unpacker that deserializes objects from a specified readable channel. * - * @param channel - * @return + * @param channel The input channel that provides sequence of bytes + * @return A new MessageUnpacker instance */ public MessageUnpacker newUnpacker(ReadableByteChannel channel) { @@ -516,10 +609,12 @@ public MessageUnpacker newUnpacker(ReadableByteChannel channel) } /** - * Create an unpacker that reads the data from a given byte array + * Creates an unpacker that deserializes objects from a specified byte array. + *

+ * This method provides an optimized implementation of newDefaultUnpacker(new ByteArrayInputStream(contents)). * - * @param contents - * @return + * @param contents The byte array that contains packed objects in MessagePack format + * @return A new MessageUnpacker instance that will never throw IOException */ public MessageUnpacker newUnpacker(byte[] contents) { @@ -527,10 +622,14 @@ public MessageUnpacker newUnpacker(byte[] contents) } /** - * Create an unpacker that reads the data from a given byte array [offset, offset+size) + * Creates an unpacker that deserializes objects from subarray of a specified byte array. + *

+ * This method provides an optimized implementation of newDefaultUnpacker(new ByteArrayInputStream(contents, offset, length)). * - * @param contents - * @return + * @param contents The byte array that contains packed objects + * @param offset The index of the first byte + * @param length The number of bytes + * @return A new MessageUnpacker instance that will never throw IOException */ public MessageUnpacker newUnpacker(byte[] contents, int offset, int length) { @@ -538,10 +637,14 @@ public MessageUnpacker newUnpacker(byte[] contents, int offset, int length) } /** - * Create an unpacker that reads the data from a given ByteBuffer + * Creates an unpacker that deserializes objects from a specified ByteBuffer. + *

+ * Note that the returned unpacker reads data from the current position of the ByteBuffer until its limit. + * However, its position does not change when unpacker reads data. You may use + * {@link MessageUnpacker#getTotalReadBytes()} to get actual amount of bytes used in ByteBuffer. * - * @param contents - * @return + * @param contents The byte buffer that contains packed objects + * @return A new MessageUnpacker instance that will never throw IOException */ public MessageUnpacker newUnpacker(ByteBuffer contents) { @@ -549,7 +652,7 @@ public MessageUnpacker newUnpacker(ByteBuffer contents) } /** - * Allow unpackBinaryHeader to read str format family (default: true) + * Allows unpackBinaryHeader to read str format family (default: true) */ public UnpackerConfig withAllowReadingStringAsBinary(boolean enable) { @@ -564,7 +667,7 @@ public boolean getAllowReadingStringAsBinary() } /** - * Allow unpackString and unpackRawStringHeader and unpackString to read bin format family (default: true) + * Allows unpackString and unpackRawStringHeader and unpackString to read bin format family (default: true) */ public UnpackerConfig withAllowReadingBinaryAsString(boolean enable) { @@ -579,7 +682,7 @@ public boolean getAllowReadingBinaryAsString() } /** - * Action when encountered a malformed input (default: REPLACE) + * Sets action when encountered a malformed input (default: REPLACE) */ public UnpackerConfig withActionOnMalformedString(CodingErrorAction action) { @@ -594,7 +697,7 @@ public CodingErrorAction getActionOnMalformedString() } /** - * Action when an unmappable character is found (default: REPLACE) + * Sets action when an unmappable character is found (default: REPLACE) */ public UnpackerConfig withActionOnUnmappableString(CodingErrorAction action) { diff --git a/msgpack-core/src/main/java/org/msgpack/core/MessagePacker.java b/msgpack-core/src/main/java/org/msgpack/core/MessagePacker.java index 5559fd4ad..423886fd8 100644 --- a/msgpack-core/src/main/java/org/msgpack/core/MessagePacker.java +++ b/msgpack-core/src/main/java/org/msgpack/core/MessagePacker.java @@ -67,21 +67,65 @@ import static org.msgpack.core.Preconditions.checkNotNull; /** - * Writer of message packed data. - *

+ * MessagePack serializer that converts objects into binary. + * You can use factory methods of {@link MessagePack} class or {@link MessagePack.PackerConfig} class to create + * an instance. *

- * MessagePacker provides packXXX methods for writing values in the message pack format. - * To write raw string or binary data, first use packRawStringHeader or packBinaryHeader to specify the data length, - * then call writePayload(...) method. - *

- *

+ * This class provides following primitive methods to write MessagePack values. These primitive methods write + * short bytes (1 to 7 bytes) to the internal buffer at once. There also some complex methods for convenience. *

- * MessagePacker class has no guarantee to produce the correct message-pack format data if it is not used correctly: - * packXXX methods of primitive values always produce the correct format, but - * packXXXHeader (e.g. array, map, ext) must be followed by correct number of array/map/ext type values. - * packRawStringHeader(length) and packBinaryHeader(length) must be followed by writePayload( ... length) to supply - * the binary data of the specified length in the header. - *

+ * Primitive methods: + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
Java typePacker methodMessagePack type
null{@link #packNil()}Nil
boolean{@link #packBoolean(boolean)}Boolean
byte{@link #packByte(byte)}Integer
short{@link #packShort(short)}Integer
int{@link #packInt(int)}Integer
long{@link #packLong(long)}Integer
BigInteger{@link #packBigInteger(BigInteger)}Integer
float{@link #packFloat(float)}Float
double{@link #packDouble(double)}Float
byte[]{@link #packBinaryHeader(int)}Binary
String{@link #packRawStringHeader(int)}String
List{@link #packArrayHeader(int)}Array
Map{@link #packMapHeader(int)}Map
custom user type{@link #packExtensionTypeHeader(byte, int)}Extension
+ * + *

+ * Complex methods: + * + * + * + * + * + *
Java typePacker methodMessagePack type
String{@link #packString(String)}String
{@link Value}{@link #packValue(Value)}
+ * + *

+ * To write a byte array, first you call {@link #packBinaryHeader} method with length of the byte array. Then, + * you call {@link #writePayload(byte[], int, int)} or {@link #addPayload(byte[], int, int)} method to write the + * contents. + * + *

+ * To write a List, Collection or array, first you call {@link #packArrayHeader(int)} method with the number of + * elements. Then, you call packer methods for each element. You don't have to call anything at the end of + * iteration. + * + *

+ * To write a Map, first you call {@link #packMapHeader(int)} method with size of the map. Then, for each pair, + * you call packer methods for key first, and then value. You will call packer methods twice as many time as the + * size of the map. You don't have to call anything at the end of iteration. + * + *

+ * Note that packXxxHeader methods don't validate number of elements. You must call packer methods for correct + * number of times to produce valid MessagePack data. + * + *

+ * When IOException is thrown, primitive methods guarantee that all data is written to the internal buffer or no data + * is written. This is convenient behavior when you use a non-blocking output channel that may not be writable + * immediately. */ public class MessagePacker implements Closeable, Flushable @@ -92,6 +136,9 @@ public class MessagePacker private final boolean str8FormatSupport; + /** + * Current internal buffer. + */ protected MessageBufferOutput out; private MessageBuffer buffer; @@ -126,10 +173,18 @@ protected MessagePacker(MessageBufferOutput out, MessagePack.PackerConfig config } /** - * Reset output. This method doesn't close the old resource. + * Replaces underlaying output. + *

+ * This method flushes current internal buffer to the output, swaps it with the new given output, then returns + * the old output. + * + *

+ * This method doesn't close the old output. * * @param out new output - * @return the old resource + * @return the old output + * @throws IOException when underlaying output throws IOException + * @throws NullPointerException the given output is null */ public MessageBufferOutput reset(MessageBufferOutput out) throws IOException @@ -148,11 +203,26 @@ public MessageBufferOutput reset(MessageBufferOutput out) return old; } + /** + * Returns total number of written bytes. + *

+ * This method returns total of amount of data flushed to the underlaying output plus size of current + * internal buffer. + * + *

+ * Calling {@link #reset(MessageBufferOutput)} resets this number to 0. + */ public long getTotalWrittenBytes() { return totalFlushBytes + position; } + /** + * Flushes internal buffer to the underlaying output. + *

+ * This method also calls flush method of the underlaying output after writing internal buffer. + */ + @Override public void flush() throws IOException { @@ -162,6 +232,12 @@ public void flush() out.flush(); } + /** + * Closes underlaying output. + *

+ * This method flushes internal buffer before closing. + */ + @Override public void close() throws IOException { @@ -278,6 +354,14 @@ private void writeLong(long v) position += 8; } + /** + * Writes a Nil value. + * + * This method writes a nil byte. + * + * @return this + * @throws IOException when underlaying output throws IOException + */ public MessagePacker packNil() throws IOException { @@ -285,6 +369,14 @@ public MessagePacker packNil() return this; } + /** + * Writes a Boolean value. + * + * This method writes a true byte or a false byte. + * + * @return this + * @throws IOException when underlaying output throws IOException + */ public MessagePacker packBoolean(boolean b) throws IOException { @@ -292,6 +384,16 @@ public MessagePacker packBoolean(boolean b) return this; } + /** + * Writes an Integer value. + * + *

+ * This method writes an integer using the smallest format from the int format family. + * + * @param b the integer to be written + * @return this + * @throws IOException when underlaying output throws IOException + */ public MessagePacker packByte(byte b) throws IOException { @@ -304,6 +406,16 @@ public MessagePacker packByte(byte b) return this; } + /** + * Writes an Integer value. + * + *

+ * This method writes an integer using the smallest format from the int format family. + * + * @param v the integer to be written + * @return this + * @throws IOException when underlaying output throws IOException + */ public MessagePacker packShort(short v) throws IOException { @@ -329,6 +441,16 @@ else if (v < (1 << 7)) { return this; } + /** + * Writes an Integer value. + * + *

+ * This method writes an integer using the smallest format from the int format family. + * + * @param v the integer to be written + * @return this + * @throws IOException when underlaying output throws IOException + */ public MessagePacker packInt(int r) throws IOException { @@ -361,6 +483,16 @@ else if (r < (1 << 16)) { return this; } + /** + * Writes an Integer value. + * + *

+ * This method writes an integer using the smallest format from the int format family. + * + * @param v the integer to be written + * @return this + * @throws IOException when underlaying output throws IOException + */ public MessagePacker packLong(long v) throws IOException { @@ -407,6 +539,16 @@ else if (v < (1 << 7)) { return this; } + /** + * Writes an Integer value. + * + *

+ * This method writes an integer using the smallest format from the int format family. + * + * @param bi the integer to be written + * @return this + * @throws IOException when underlaying output throws IOException + */ public MessagePacker packBigInteger(BigInteger bi) throws IOException { @@ -422,6 +564,16 @@ else if (bi.bitLength() == 64 && bi.signum() == 1) { return this; } + /** + * Writes a Float value. + * + *

+ * This method writes a float value using float format family. + * + * @param bi the integer to be written + * @return this + * @throws IOException when underlaying output throws IOException + */ public MessagePacker packFloat(float v) throws IOException { @@ -429,6 +581,16 @@ public MessagePacker packFloat(float v) return this; } + /** + * Writes a Float value. + * + *

+ * This method writes a float value using float format family. + * + * @param bi the integer to be written + * @return this + * @throws IOException when underlaying output throws IOException + */ public MessagePacker packDouble(double v) throws IOException { @@ -497,11 +659,14 @@ private int encodeStringToBufferAt(int pos, String s) private static final int UTF_8_MAX_CHAR_SIZE = 6; /** - * Pack the input String in UTF-8 encoding + * Writes a String vlaue in UTF-8 encoding. * - * @param s - * @return - * @throws IOException + *

+ * This method writes a UTF-8 string using the smallest format from the str format family by default. If {@link MessagePack.PackerConfig#withStr8FormatSupport(boolean)} is set to false, smallest format from the str format family excepting str8 format. + * + * @param s the string to be written + * @return this + * @throws IOException when underlaying output throws IOException */ public MessagePacker packString(String s) throws IOException @@ -581,6 +746,17 @@ else if (s.length() < (1 << 16)) { return this; } + /** + * Writes header of an Array value. + *

+ * You will call other packer methods for each element after this method call. + *

+ * You don't have to call anything at the end of iteration. + * + * @param arraySize number of elements to be written + * @return this + * @throws IOException when underlaying output throws IOException + */ public MessagePacker packArrayHeader(int arraySize) throws IOException { @@ -600,6 +776,18 @@ else if (arraySize < (1 << 16)) { return this; } + /** + * Writes header of a Map value. + *

+ * After this method call, for each key-value pair, you will call packer methods for key first, and then value. + * You will call packer methods twice as many time as the size of the map. + *

+ * You don't have to call anything at the end of iteration. + * + * @param mapSize number of pairs to be written + * @return this + * @throws IOException when underlaying output throws IOException + */ public MessagePacker packMapHeader(int mapSize) throws IOException { @@ -619,6 +807,13 @@ else if (mapSize < (1 << 16)) { return this; } + /** + * Writes a dynamically typed value. + * + * @param v the value to be written + * @return this + * @throws IOException when underlaying output throws IOException + */ public MessagePacker packValue(Value v) throws IOException { @@ -626,6 +821,15 @@ public MessagePacker packValue(Value v) return this; } + /** + * Writes header of an Extension value. + *

+ * You will call {@link #writePayload(byte[])} or {@link #addPayload(byte[])} method to write body binary. + * + * @param len number of bytes of a payload binary to be written + * @return this + * @throws IOException when underlaying output throws IOException + */ public MessagePacker packExtensionTypeHeader(byte extType, int payloadLen) throws IOException { @@ -669,6 +873,15 @@ else if (payloadLen < (1 << 16)) { return this; } + /** + * Writes header of a Binary value. + *

+ * You will call {@link #writePayload(byte[])} or {@link #addPayload(byte[])} method to write body binary. + * + * @param len number of bytes of a binary to be written + * @return this + * @throws IOException when underlaying output throws IOException + */ public MessagePacker packBinaryHeader(int len) throws IOException { @@ -684,6 +897,18 @@ else if (len < (1 << 16)) { return this; } + /** + * Writes header of a String value. + *

+ * Length must be number of bytes of a string in UTF-8 encoding. + *

+ * You will call {@link #writePayload(byte[])} or {@link #addPayload(byte[])} method to write body of the + * UTF-8 encoded string. + * + * @param len number of bytes of a UTF-8 string to be written + * @return this + * @throws IOException when underlaying output throws IOException + */ public MessagePacker packRawStringHeader(int len) throws IOException { @@ -703,12 +928,13 @@ else if (len < (1 << 16)) { } /** - * Writes buffer to the output. - * This method is used with packRawStringHeader or packBinaryHeader. + * Writes a byte array to the output. + *

+ * This method is used with {@link #packRawStringHeader(int)} or {@link #packBinaryHeader(int)} methods. * * @param src the data to add * @return this - * @throws IOException + * @throws IOException when underlaying output throws IOException */ public MessagePacker writePayload(byte[] src) throws IOException @@ -717,14 +943,15 @@ public MessagePacker writePayload(byte[] src) } /** - * Writes buffer to the output. - * This method is used with packRawStringHeader or packBinaryHeader. + * Writes a byte array to the output. + *

+ * This method is used with {@link #packRawStringHeader(int)} or {@link #packBinaryHeader(int)} methods. * * @param src the data to add * @param off the start offset in the data * @param len the number of bytes to add * @return this - * @throws IOException + * @throws IOException when underlaying output throws IOException */ public MessagePacker writePayload(byte[] src, int off, int len) throws IOException @@ -743,13 +970,15 @@ public MessagePacker writePayload(byte[] src, int off, int len) } /** - * Writes buffer to the output. - * Unlike writePayload method, addPayload method doesn't copy the source data. It means that the caller - * must not modify the data after calling this method. + * Writes a byte array to the output. + *

+ * Unlike {@link #writePayload} method, this method doesn't copy the byte array even when given byte array + * is shorter than {@link MessagePack.PackerConfig#withBufferFlushThreshold(int)}. This is faster than + * {@link writePayload} method but caller must not modify the byte array after calling this method. * * @param src the data to add * @return this - * @throws IOException + * @throws IOException when underlaying output throws IOException */ public MessagePacker addPayload(byte[] src) throws IOException @@ -758,15 +987,17 @@ public MessagePacker addPayload(byte[] src) } /** - * Writes buffer to the output. - * Unlike writePayload method, addPayload method doesn't copy the source data. It means that the caller - * must not modify the data after calling this method. + * Writes a byte array to the output. + *

+ * Unlike {@link #writePayload} method, this method doesn't copy the byte array even when given byte array + * is shorter than {@link MessagePack.PackerConfig#withBufferFlushThreshold(int)}. This is faster than + * {@link writePayload} method but caller must not modify the byte array after calling this method. * * @param src the data to add * @param off the start offset in the data * @param len the number of bytes to add * @return this - * @throws IOException + * @throws IOException when underlaying output throws IOException */ public MessagePacker addPayload(byte[] src, int off, int len) throws IOException diff --git a/msgpack-core/src/main/java/org/msgpack/core/MessageUnpacker.java b/msgpack-core/src/main/java/org/msgpack/core/MessageUnpacker.java index 0696cd54c..0b9c575bf 100644 --- a/msgpack-core/src/main/java/org/msgpack/core/MessageUnpacker.java +++ b/msgpack-core/src/main/java/org/msgpack/core/MessageUnpacker.java @@ -40,31 +40,112 @@ import static org.msgpack.core.Preconditions.checkNotNull; /** - * MessageUnpacker lets an application read message-packed values from a data stream. - * The application needs to call {@link #getNextFormat()} followed by an appropriate unpackXXX method according to the the returned format type. - *

- * 

- * 
+ * MessagePack deserializer that converts binary into objects.
+ * You can use factory methods of {@link MessagePack} class or {@link MessagePack.UnpackerConfig} class to create
+ * an instance.
+ * To read values as statically-typed Java objects, there are two typical use cases.
+ * 

+ * One use case is to read objects as {@link Value} using {@link #unpackValue} method. A {@link Value} object
+ * contains type of the deserialized value as well as the value itself so that you can inspect type of the
+ * deserialized values later. You can repeat {@link #unpackValue} until {@link hasNext()} method returns false so
+ * that you can deserialize sequence of MessagePack values.
+ * 

+ * The other use case is to use {@link #getNextFormat()} and {@link MessageFormat#getValueType()} methods followed
+ * by unpackXxx methods corresponding to returned type. Following code snipet is a typical application code:
+ * 

  *     MessageUnpacker unpacker = MessagePack.newDefaultUnpacker(...);
  *     while(unpacker.hasNext()) {
- *         MessageFormat f = unpacker.getNextFormat();
- *         switch(f) {
- *             case MessageFormat.POSFIXINT:
- *             case MessageFormat.INT8:
- *             case MessageFormat.UINT8: {
- *                int v = unpacker.unpackInt();
- *                break;
+ *         MessageFormat format = unpacker.getNextFormat();
+ *         ValueType type = format.getValueType();
+ *         int length;
+ *         ExtensionTypeHeader extension;
+ *         switch(type) {
+ *             case NIL:
+ *                 unpacker.unpackNil();
+ *                 break;
+ *             case BOOLEAN:
+ *                 unpacker.unpackBoolean();
+ *                 break;
+ *             case INTEGER:
+ *                 switch (format) {
+ *                 case UINT64:
+ *                     unpacker.unpackBigInteger();
+ *                     break;
+ *                 case INT64:
+ *                 case UINT32:
+ *                     unpacker.unpackLong();
+ *                     break;
+ *                 default:
+ *                     unpacker.unpackInt();
+ *                     break;
+ *                 }
+ *                 break;
+ *             case FLOAT:
+ *                 unpacker.unpackDouble();
+ *                 break;
+ *             case STRING:
+ *                 unpacker.unpackString();
+ *                 break;
+ *             case BINARY:
+ *                 length = unpacker.unpackBinaryHeader();
+ *                 unpacker.readPayload(new byte[length]);
+ *                 break;
+ *             case ARRAY:
+ *                 length = unpacker.unpackArrayHeader();
+ *                 for (int i = 0; i < length; i++) {
+ *                     readRecursively(unpack);
+ *                 }
+ *                 break;
+ *             case MAP:
+ *                 length = unpacker.unpackMapHeader();
+ *                 for (int i = 0; i < length; i++) {
+ *                     readRecursively(unpack);  // key
+ *                     readRecursively(unpack);  // value
+ *                 }
+ *                 break;
+ *             case EXTENSION:
+ *                 extension = unpacker.unpackExtensionTypeHeader();
+ *                 unpacker.readPayload(new byte[extension.getLength()]);
+ *                 break;
  *             }
- *             case MessageFormat.STRING: {
- *                String v = unpacker.unpackString();
- *                break;
- *             }
- *             // ...
- *       }
+ *         }
  *     }
  *
- * 
- * 

+ * 

+ * Following methods correspond to the MessagePack types:
+ *
+ * 
+ *   
+ *   
+ *   
+ *   
+ *   
+ *   
+ *   
+ *   
+ *   
+ *   
+ *   
+ *   
+ *   
+ *   
+ *   
+ *   
+ * 
MessagePack typeUnpacker methodJava type
Nil{@link #unpackNil()}null
Boolean{@link #unpackBoolean()}boolean
Integer{@link #unpackByte()}byte
Integer{@link #unpackShort()}short
Integer{@link #unpackInt()}int
Integer{@link #unpackLong()}long
Integer{@link #unpackBigInteger()}BigInteger
Float{@link #unpackFloat()}float
Float{@link #unpackDouble()}double
Binary{@link #unpackBinaryHeader()}byte array
String{@link #unpackRawStringHeader()}String
String{@link #unpackString()}String
Array{@link #unpackArrayHeader()}Array
Map{@link #unpackMapHeader()}Map
Extension{@link #unpackExtensionTypeHeader()}{@link ExtensionTypeHeader}

+ *
+ * 

+ * To read a byte array, first you call {@link #unpackBinaryHeader} method to get length of the byte array. Then,
+ * you call {@link #readPayload(int)} or {@link #readPayloadAsReference(int)} method to read the the contents.
+ *
+ * 

+ * To read an Array type, first you call {@link #unpackArrayHeader()} method to get number of elements. Then,
+ * you call unpacker methods for each element. You don't have to call anything at the end of iteration.
+ *
+ * 

+ * To read a Map, first you call {@link #unpackMapHeader(int)} method to get number of pairs of the map. Then,
+ * for each pair, you call unpacker methods for key first, and then value. You will call unpacker methods twice
+ * as many time as the returned count. You don't have to call anything at the end of iteration.
+ *
  */
 public class MessageUnpacker
         implements Closeable
@@ -139,10 +220,18 @@ protected MessageUnpacker(MessageBufferInput in, MessagePack.UnpackerConfig conf
     }
 
     /**
-     * Reset input. This method doesn't close the old resource.
+     * Replaces underlaying input.
+     * 

+     * This method clears internal buffer, swaps the underlaying input with the new given input, then returns
+     * the old input.
      *
-     * @param in new input
-     * @return the old resource
+     * 

+     * This method doesn't close the old input.
+     *
+     * @param out new input
+     * @return the old input
+     * @throws IOException never happens unless a subclass overrides this method
+     * @throws NullPointerException the given input is null
      */
     public MessageBufferInput reset(MessageBufferInput in)
             throws IOException
@@ -160,6 +249,15 @@ public MessageBufferInput reset(MessageBufferInput in)
         return old;
     }
 
+    /**
+     * Returns total number of read bytes.
+     * 

+     * This method returns total of amount of data consumed from the underlaying input minus size of data
+     * remained still unused in the current internal buffer.
+     *
+     * 

+     * Calling {@link #reset(MessageBufferInput)} resets this number to 0.
+     */
     public long getTotalReadBytes()
     {
         return totalReadBytes + position;
@@ -274,13 +372,18 @@ private boolean ensureBuffer()
     }
 
     /**
-     * Returns the next MessageFormat type. This method should be called after {@link #hasNext()} returns true.
-     * If {@link #hasNext()} returns false, calling this method throws {@link MessageInsufficientBufferException}.
-     * 

-     * This method does not proceed the internal cursor.
+     * Returns format of the next value.
+     *
+     * 

+     * Note that this method doesn't consume data from the internal buffer unlike the other unpack methods.
+     * Calling this method twice will return the same value.
+     *
+     * 

+     * To not throw {@link MessageInsufficientBufferException}, this method should be called only when
+     * {@link #hasNext()} returns true.
      *
      * @return the next MessageFormat
-     * @throws IOException when failed to read the input data.
+     * @throws IOException when underlaying input throws IOException
      * @throws MessageInsufficientBufferException when the end of file reached, i.e. {@link #hasNext()} == false.
      */
     public MessageFormat getNextFormat()
@@ -612,6 +715,13 @@ public Variable unpackValue(Variable var)
         }
     }
 
+    /**
+     * Reads a Nil byte.
+     *
+     * @return the read value
+     * @throws MessageTypeException when value is not MessagePack Nil type
+     * @throws IOException when underlaying input throws IOException
+     */
     public void unpackNil()
             throws IOException
     {
@@ -622,6 +732,13 @@ public void unpackNil()
         throw unexpected("Nil", b);
     }
 
+    /**
+     * Reads true or false.
+     *
+     * @return the read value
+     * @throws MessageTypeException when value is not MessagePack Boolean type
+     * @throws IOException when underlaying input throws IOException
+     */
     public boolean unpackBoolean()
             throws IOException
     {
@@ -635,6 +752,16 @@ else if (b == Code.TRUE) {
         throw unexpected("boolean", b);
     }
 
+    /**
+     * Reads a byte.
+     *
+     * This method throws {@link MessageIntegerOverflowException} if the value doesn't fit in the range of byte. This may happen when {@link #getNextFormat()} returns UINT8, INT16, or larger integer formats.
+     *
+     * @return the read value
+     * @throws MessageIntegerOverflowException when value doesn't fit in the range of byte
+     * @throws MessageTypeException when value is not MessagePack Integer type
+     * @throws IOException when underlaying input throws IOException
+     */
     public byte unpackByte()
             throws IOException
     {
@@ -692,6 +819,16 @@ public byte unpackByte()
         throw unexpected("Integer", b);
     }
 
+    /**
+     * Reads a short.
+     *
+     * This method throws {@link MessageIntegerOverflowException} if the value doesn't fit in the range of short. This may happen when {@link #getNextFormat()} returns UINT16, INT32, or larger integer formats.
+     *
+     * @return the read value
+     * @throws MessageIntegerOverflowException when value doesn't fit in the range of short
+     * @throws MessageTypeException when value is not MessagePack Integer type
+     * @throws IOException when underlaying input throws IOException
+     */
     public short unpackShort()
             throws IOException
     {
@@ -743,6 +880,16 @@ public short unpackShort()
         throw unexpected("Integer", b);
     }
 
+    /**
+     * Reads a int.
+     *
+     * This method throws {@link MessageIntegerOverflowException} if the value doesn't fit in the range of int. This may happen when {@link #getNextFormat()} returns UINT32, INT64, or larger integer formats.
+     *
+     * @return the read value
+     * @throws MessageIntegerOverflowException when value doesn't fit in the range of int
+     * @throws MessageTypeException when value is not MessagePack Integer type
+     * @throws IOException when underlaying input throws IOException
+     */
     public int unpackInt()
             throws IOException
     {
@@ -788,6 +935,16 @@ public int unpackInt()
         throw unexpected("Integer", b);
     }
 
+    /**
+     * Reads a long.
+     *
+     * This method throws {@link MessageIntegerOverflowException} if the value doesn't fit in the range of long. This may happen when {@link #getNextFormat()} returns UINT64.
+     *
+     * @return the read value
+     * @throws MessageIntegerOverflowException when value doesn't fit in the range of long
+     * @throws MessageTypeException when value is not MessagePack Integer type
+     * @throws IOException when underlaying input throws IOException
+     */
     public long unpackLong()
             throws IOException
     {
@@ -832,6 +989,13 @@ public long unpackLong()
         throw unexpected("Integer", b);
     }
 
+    /**
+     * Reads a BigInteger.
+     *
+     * @return the read value
+     * @throws MessageTypeException when value is not MessagePack Integer type
+     * @throws IOException when underlaying input throws IOException
+     */
     public BigInteger unpackBigInteger()
             throws IOException
     {
@@ -879,6 +1043,15 @@ public BigInteger unpackBigInteger()
         throw unexpected("Integer", b);
     }
 
+    /**
+     * Reads a float.
+     *
+     * This method rounds value to the range of float when precision of the read value is larger than the range of float. This may happen when {@link #getNextFormat()} returns FLOAT64.
+     *
+     * @return the read value
+     * @throws MessageTypeException when value is not MessagePack Float type
+     * @throws IOException when underlaying input throws IOException
+     */
     public float unpackFloat()
             throws IOException
     {
@@ -894,6 +1067,13 @@ public float unpackFloat()
         throw unexpected("Float", b);
     }
 
+    /**
+     * Reads a double.
+     *
+     * @return the read value
+     * @throws MessageTypeException when value is not MessagePack Float type
+     * @throws IOException when underlaying input throws IOException
+     */
     public double unpackDouble()
             throws IOException
     {
@@ -1053,6 +1233,18 @@ private String decodeStringFastPath(int length)
         }
     }
 
+    /**
+     * Reads header of an array.
+     *
+     * 

+     * This method returns number of elements to be read. After this method call, you call unpacker methods for
+     * each element. You don't have to call anything at the end of iteration.
+     *
+     * @return the size of the array to be read
+     * @throws MessageTypeException when value is not MessagePack Array type
+     * @throws MessageSizeException when size of the array is larger than 2^31 - 1
+     * @throws IOException when underlaying input throws IOException
+     */
     public int unpackArrayHeader()
             throws IOException
     {
@@ -1073,6 +1265,19 @@ public int unpackArrayHeader()
         throw unexpected("Array", b);
     }
 
+    /**
+     * Reads header of a map.
+     *
+     * 

+     * This method returns number of pairs to be read. After this method call, for each pair, you call unpacker
+     * methods for key first, and then value. You will call unpacker methods twice as many time as the returned
+     * count. You don't have to call anything at the end of iteration.
+     *
+     * @return the size of the map to be read
+     * @throws MessageTypeException when value is not MessagePack Map type
+     * @throws MessageSizeException when size of the map is larger than 2^31 - 1
+     * @throws IOException when underlaying input throws IOException
+     */
     public int unpackMapHeader()
             throws IOException
     {
@@ -1198,6 +1403,22 @@ public int unpackRawStringHeader()
         throw unexpected("String", b);
     }
 
+    /**
+     * Reads header of a binary.
+     *
+     * 

+     * This method returns number of bytes to be read. After this method call, you call a readPayload method such as
+     * {@link #readPayload(int)} with the returned count.
+     *
+     * 

+     * You can divide readPayload method into multiple calls. In this case, you must repeat readPayload methods
+     * until total amount of bytes becomes equal to the returned count.
+     *
+     * @return the size of the map to be read
+     * @throws MessageTypeException when value is not MessagePack Map type
+     * @throws MessageSizeException when size of the map is larger than 2^31 - 1
+     * @throws IOException when underlaying input throws IOException
+     */
     public int unpackBinaryHeader()
             throws IOException
     {
@@ -1243,6 +1464,16 @@ private void skipPayload(int numBytes)
         }
     }
 
+    /**
+     * Reads payload bytes of binary, extension, or raw string types.
+     *
+     * 

+     * This consumes bytes, copies them to the specified buffer, and moves forward position of the byte buffer
+     * until ByteBuffer.remaining() returns 0.
+     *
+     * @param dst the byte buffer into which the data is read
+     * @throws IOException when underlaying input throws IOException
+     */
     public void readPayload(ByteBuffer dst)
             throws IOException
     {
@@ -1261,12 +1492,35 @@ public void readPayload(ByteBuffer dst)
         }
     }
 
+    /**
+     * Reads payload bytes of binary, extension, or raw string types.
+     *
+     * This consumes specified amount of bytes into the specified byte array.
+     *
+     * 

+     * This method is equivalent to readPayload(dst, 0, dst.length).
+     *
+     * @param dst the byte array into which the data is read
+     * @throws IOException when underlaying input throws IOException
+     */
     public void readPayload(byte[] dst)
             throws IOException
     {
         readPayload(dst, 0, dst.length);
     }
 
+    /**
+     * Reads payload bytes of binary, extension, or raw string types.
+     *
+     * This method allocates a new byte array and consumes specified amount of bytes into the byte array.
+     *
+     * 

+     * This method is equivalent to readPayload(new byte[length]).
+     *
+     * @param length number of bytes to be read
+     * @return the new byte array
+     * @throws IOException when underlaying input throws IOException
+     */
     public byte[] readPayload(int length)
             throws IOException
     {
@@ -1276,12 +1530,14 @@ public byte[] readPayload(int length)
     }
 
     /**
-     * Read up to len bytes of data into the destination array
+     * Reads payload bytes of binary, extension, or raw string types.
      *
-     * @param dst the buffer into which the data is read
+     * This consumes specified amount of bytes into the specified byte array.
+     *
+     * @param dst the byte array into which the data is read
      * @param off the offset in the dst array
      * @param len the number of bytes to read
-     * @throws IOException
+     * @throws IOException when underlaying input throws IOException
      */
     public void readPayload(byte[] dst, int off, int len)
             throws IOException
@@ -1290,6 +1546,17 @@ public void readPayload(byte[] dst, int off, int len)
         readPayload(ByteBuffer.wrap(dst, off, len));
     }
 
+    /**
+     * Reads payload bytes of binary, extension, or raw string types as a reference to internal buffer.
+     *
+     * 

+     * This consumes specified amount of bytes and returns its reference or copy. This method tries to
+     * return reference as much as possible because it is faster. However, it may copy data to a newly
+     * allocated buffer if reference is not applicable.
+     *
+     * @param length number of bytes to be read
+     * @throws IOException when underlaying input throws IOException
+     */
     public MessageBuffer readPayloadAsReference(int length)
             throws IOException
     {
@@ -1328,6 +1595,11 @@ private int readNextLength32()
         return u32;
     }
 
+    /**
+     * Closes underlaying input.
+     *
+     * @throws IOException
+     */
     @Override
     public void close()
             throws IOException

From e5999106bb2c86caedad1c5120a949208163ec96 Mon Sep 17 00:00:00 2001
From: Sadayuki Furuhashi 
Date: Mon, 24 Oct 2016 13:37:04 -0700
Subject: [PATCH 2/5] Adding JavaDoc - part 2

---
 .../org/msgpack/core/MessageBufferPacker.java | 33 ++++++++-
 .../java/org/msgpack/core/MessagePack.java    |  6 +-
 .../java/org/msgpack/core/MessagePacker.java  |  6 +-
 .../org/msgpack/core/MessageUnpacker.java     |  4 +-
 .../core/buffer/ArrayBufferOutput.java        | 37 +++++++++-
 .../msgpack/core/buffer/MessageBuffer.java    | 23 ++++---
 .../core/buffer/MessageBufferInput.java       | 27 ++++++--
 .../core/buffer/MessageBufferOutput.java      | 34 +++++++---
 .../java/org/msgpack/value/ArrayValue.java    |  2 +-
 .../java/org/msgpack/value/BinaryValue.java   |  2 +-
 .../java/org/msgpack/value/BooleanValue.java  |  2 +-
 .../org/msgpack/value/ExtensionValue.java     |  2 +-
 .../java/org/msgpack/value/FloatValue.java    |  2 +-
 .../msgpack/value/ImmutableArrayValue.java    |  5 ++
 .../msgpack/value/ImmutableBinaryValue.java   |  7 ++
 .../msgpack/value/ImmutableBooleanValue.java  |  5 ++
 .../value/ImmutableExtensionValue.java        |  5 ++
 .../msgpack/value/ImmutableFloatValue.java    |  7 ++
 .../msgpack/value/ImmutableIntegerValue.java  |  5 ++
 .../org/msgpack/value/ImmutableMapValue.java  |  5 ++
 .../org/msgpack/value/ImmutableNilValue.java  |  3 +
 .../msgpack/value/ImmutableNumberValue.java   |  6 ++
 .../org/msgpack/value/ImmutableRawValue.java  |  8 +++
 .../msgpack/value/ImmutableStringValue.java   |  6 ++
 .../org/msgpack/value/ImmutableValue.java     |  3 +
 .../java/org/msgpack/value/IntegerValue.java  |  2 +-
 .../main/java/org/msgpack/value/MapValue.java |  2 +-
 .../main/java/org/msgpack/value/NilValue.java |  2 +-
 .../java/org/msgpack/value/NumberValue.java   |  2 +-
 .../main/java/org/msgpack/value/RawValue.java |  2 +-
 .../java/org/msgpack/value/StringValue.java   |  2 +-
 .../main/java/org/msgpack/value/Value.java    | 67 ++++++++++++++++---
 .../java/org/msgpack/value/ValueType.java     |  8 ++-
 33 files changed, 279 insertions(+), 53 deletions(-)

diff --git a/msgpack-core/src/main/java/org/msgpack/core/MessageBufferPacker.java b/msgpack-core/src/main/java/org/msgpack/core/MessageBufferPacker.java
index 7483010b2..3f6b732a1 100644
--- a/msgpack-core/src/main/java/org/msgpack/core/MessageBufferPacker.java
+++ b/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.
+ * 

+ * 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,11 +56,22 @@ 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.
+     * 

+     * 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 {
@@ -69,6 +84,14 @@ public byte[] toByteArray()
         return getArrayBufferOut().toByteArray();
     }
 
+    /**
+     * Gets the written data as a MessageBuffer.
+     * 

+     * 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 {
@@ -81,6 +104,14 @@ public MessageBuffer toMessageBuffer()
         return getArrayBufferOut().toMessageBuffer();
     }
 
+    /**
+     * Returns the written data as a list of MessageBuffer.
+     * 

+     * 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 toBufferList()
     {
         try {
diff --git a/msgpack-core/src/main/java/org/msgpack/core/MessagePack.java b/msgpack-core/src/main/java/org/msgpack/core/MessagePack.java
index 2c84d2328..ed8b1e405 100644
--- a/msgpack-core/src/main/java/org/msgpack/core/MessagePack.java
+++ b/msgpack-core/src/main/java/org/msgpack/core/MessagePack.java
@@ -35,7 +35,7 @@
 /**
  * Convenience class to build packer and unpacker classes.
  *
- * You may choose factory method as following
+ * You can select an appropriate factory method as following.
  *
  * 

  * Deserializing objects from binary:
@@ -70,12 +70,12 @@ public class MessagePack
     public static final Charset UTF8 = Charset.forName("UTF-8");
 
     /**
-     * Configuration of a {@link MessagePacker} created by {@link #newDefaultPacker(MessageBufferOutput)} and {@link #newDefaultBufferPacker()} methods.
+     * Configuration of a {@link MessagePacker} used by {@link #newDefaultPacker(MessageBufferOutput)} and {@link #newDefaultBufferPacker()} methods.
      */
     public static final PackerConfig DEFAULT_PACKER_CONFIG = new PackerConfig();
 
     /**
-     * Configuration of a {@link MessageUnpacker} created by {@link #newDefaultUnpacker(MessageBufferInput)} methods.
+     * Configuration of a {@link MessageUnpacker} used by {@link #newDefaultUnpacker(MessageBufferInput)} methods.
      */
     public static final UnpackerConfig DEFAULT_UNPACKER_CONFIG = new UnpackerConfig();
 
diff --git a/msgpack-core/src/main/java/org/msgpack/core/MessagePacker.java b/msgpack-core/src/main/java/org/msgpack/core/MessagePacker.java
index 423886fd8..0c61b4bd1 100644
--- a/msgpack-core/src/main/java/org/msgpack/core/MessagePacker.java
+++ b/msgpack-core/src/main/java/org/msgpack/core/MessagePacker.java
@@ -72,7 +72,7 @@
  * an instance.
  * 

  * This class provides following primitive methods to write MessagePack values. These primitive methods write
- * short bytes (1 to 7 bytes) to the internal buffer at once. There also some complex methods for convenience.
+ * short bytes (1 to 7 bytes) to the internal buffer at once. There are also some complex methods for convenience.
  * 

  * Primitive methods:
  *
@@ -110,13 +110,13 @@
  *
  * 

  * To write a List, Collection or array, first you call {@link #packArrayHeader(int)} method with the number of
- * elements. Then, you call packer methods for each element. You don't have to call anything at the end of
+ * elements. Then, you call packer methods for each element.
  * iteration.
  *
  * 

  * To write a Map, first you call {@link #packMapHeader(int)} method with size of the map. Then, for each pair,
  * you call packer methods for key first, and then value. You will call packer methods twice as many time as the
- * size of the map. You don't have to call anything at the end of iteration.
+ * size of the map.
  *
  * 

  * Note that packXxxHeader methods don't validate number of elements. You must call packer methods for correct
diff --git a/msgpack-core/src/main/java/org/msgpack/core/MessageUnpacker.java b/msgpack-core/src/main/java/org/msgpack/core/MessageUnpacker.java
index 0b9c575bf..64d26a29f 100644
--- a/msgpack-core/src/main/java/org/msgpack/core/MessageUnpacker.java
+++ b/msgpack-core/src/main/java/org/msgpack/core/MessageUnpacker.java
@@ -139,12 +139,12 @@
  *
  * 

  * To read an Array type, first you call {@link #unpackArrayHeader()} method to get number of elements. Then,
- * you call unpacker methods for each element. You don't have to call anything at the end of iteration.
+ * you call unpacker methods for each element.
  *
  * 

  * To read a Map, first you call {@link #unpackMapHeader(int)} method to get number of pairs of the map. Then,
  * for each pair, you call unpacker methods for key first, and then value. You will call unpacker methods twice
- * as many time as the returned count. You don't have to call anything at the end of iteration.
+ * as many time as the returned count.
  *
  */
 public class MessageUnpacker
diff --git a/msgpack-core/src/main/java/org/msgpack/core/buffer/ArrayBufferOutput.java b/msgpack-core/src/main/java/org/msgpack/core/buffer/ArrayBufferOutput.java
index 186a579af..df952a61a 100644
--- a/msgpack-core/src/main/java/org/msgpack/core/buffer/ArrayBufferOutput.java
+++ b/msgpack-core/src/main/java/org/msgpack/core/buffer/ArrayBufferOutput.java
@@ -19,7 +19,11 @@
 import java.util.ArrayList;
 
 /**
- * MessageBufferOutput adapter that packs data into list of byte arrays.
+ * MessageBufferOutput adapter that writes data into a list of byte arrays.
+ * 

+ * 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 ArrayBufferOutput
         implements MessageBufferOutput
@@ -39,6 +43,11 @@ public ArrayBufferOutput(int bufferSize)
         this.list = new ArrayList();
     }
 
+    /**
+     * Gets size of the written data.
+     *
+     * @return number of bytes
+     */
     public int getSize()
     {
         int size = 0;
@@ -48,6 +57,14 @@ public int getSize()
         return size;
     }
 
+    /**
+     * Gets copy of the written data as a byte array.
+     * 

+     * 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()
     {
         byte[] data = new byte[getSize()];
@@ -59,6 +76,14 @@ public byte[] toByteArray()
         return data;
     }
 
+    /**
+     * Gets the written data as a MessageBuffer.
+     * 

+     * 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()
     {
         if (list.size() == 1) {
@@ -72,13 +97,21 @@ else if (list.isEmpty()) {
         }
     }
 
+    /**
+     * Returns the written data as a list of MessageBuffer.
+     * 

+     * 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 toBufferList()
     {
         return new ArrayList(list);
     }
 
     /**
-     * Clears the internal buffers
+     * Clears the written data.
      */
     public void clear()
     {
diff --git a/msgpack-core/src/main/java/org/msgpack/core/buffer/MessageBuffer.java b/msgpack-core/src/main/java/org/msgpack/core/buffer/MessageBuffer.java
index 50d472ae5..65cb6eba3 100644
--- a/msgpack-core/src/main/java/org/msgpack/core/buffer/MessageBuffer.java
+++ b/msgpack-core/src/main/java/org/msgpack/core/buffer/MessageBuffer.java
@@ -28,12 +28,20 @@
 import static org.msgpack.core.Preconditions.checkNotNull;
 
 /**
- * MessageBuffer class is an abstraction of memory for reading/writing message packed data.
- * This MessageBuffers ensures short/int/float/long/double values are written in the big-endian order.
- * 

- * This class is optimized for fast memory access, so many methods are
- * implemented without using any interface method that produces invokeinterface call in JVM.
- * Compared to invokevirtual, invokeinterface is 30% slower in general because it needs to find a target function from the table.
+ * MessageBuffer class is an abstraction of memory with fast methods to serialize and deserialize primitive values
+ * to/from the memory. All MessageBuffer implementations ensure short/int/float/long/double values are written in
+ * big-endian order.
+ * 

+ * Applications can allocate a new buffer using {@link #allocate(int)} method, or wrap an byte array or ByteBuffer
+ * using {@link wrap(byte[], int, int)} methods. {@link wrap(ByteBuffer)} method supports both direct buffers and
+ * array-backed buffers.
+ * 

+ * MessageBuffer class itself is optimized for little-endian CPU archtectures so that JVM (HotSpot) can take advantage
+ * of the fastest JIT format which skips TypeProfile checking. To ensure this performance, applications must not load
+ * unnecessary classes such as MessagePackBE. On big-endian CPU archtectures, implementation uses subclass that
+ * includes TypeProfile overhead but still faster than ByteBuffer. On JVMs older than Java 7 and JVMs without Unsafe
+ * API (such as Android), implementation falls back to a universal implementation that uses standard ByteBuffer class
+ * internally.
  */
 public class MessageBuffer
 {
@@ -69,8 +77,7 @@ public class MessageBuffer
                 try {
                     int major = Integer.parseInt(javaVersion.substring(0, dotPos));
                     int minor = Integer.parseInt(javaVersion.substring(dotPos + 1));
-                    isJavaAtLeast7 = major > 1 || (major == 1 && minor >= 7);
-                }
+                    isJavaAtLeast7 = major > 1 || (major == 1 && minor >= 7); }
                 catch (NumberFormatException e) {
                     e.printStackTrace(System.err);
                 }
diff --git a/msgpack-core/src/main/java/org/msgpack/core/buffer/MessageBufferInput.java b/msgpack-core/src/main/java/org/msgpack/core/buffer/MessageBufferInput.java
index 46eea243e..2b19b9d99 100644
--- a/msgpack-core/src/main/java/org/msgpack/core/buffer/MessageBufferInput.java
+++ b/msgpack-core/src/main/java/org/msgpack/core/buffer/MessageBufferInput.java
@@ -19,19 +19,38 @@
 import java.io.IOException;
 
 /**
- * Provides a sequence of MessageBuffers that contains message packed data.
+ * Provides a sequence of MessageBuffer instances.
+ *
+ * A MessageBufferInput implementation has control of lifecycle of the memory so that it can reuse previously
+ * allocated memory, use memory pools, or use memory-mapped files.
  */
 public interface MessageBufferInput
         extends Closeable
 {
     /**
-     * Get a next buffer to read.
+     * Returns a next buffer to read.
      * 

-     * When this method is called, the formally allocated buffer can be safely discarded.
+     * This method should return a MessageBuffer instance that has data filled in. When this method is called twice,
+     * the previously returned buffer is no longer used. Thus implementation of this method can safely discard it.
+     * This is useful when it uses a memory pool.
      *
      * @return the next MessageBuffer, or return null if no more buffer is available.
-     * @throws IOException when error occurred when reading the data
+     * @throws IOException when IO error occurred when reading the data
      */
     MessageBuffer next()
             throws IOException;
+
+    /**
+     * Closes the input.
+     * 

+     * When this method is called, the buffer previously returned from {@link next()} method is no longer used.
+     * Thus implementation of this method can safely discard it.
+     * 

+     * If the input is already closed then invoking this method has no effect.
+     *
+     * @throws IOException when IO error occurred when closing the data source
+     */
+    @Override
+    void close()
+            throws IOException;
 }
diff --git a/msgpack-core/src/main/java/org/msgpack/core/buffer/MessageBufferOutput.java b/msgpack-core/src/main/java/org/msgpack/core/buffer/MessageBufferOutput.java
index 024414bae..9ae1b13dd 100644
--- a/msgpack-core/src/main/java/org/msgpack/core/buffer/MessageBufferOutput.java
+++ b/msgpack-core/src/main/java/org/msgpack/core/buffer/MessageBufferOutput.java
@@ -20,29 +20,40 @@
 import java.io.Flushable;
 
 /**
- * Provides a buffered output stream for packing objects
+ * Provides a buffered output stream that writes sequence of MessageBuffer instances.
+ *
+ * A MessageBufferOutput implementation has total control of the buffer memory so that it can reuse buffer memory,
+ * use buffer pools, or use memory-mapped files.
  */
 public interface MessageBufferOutput
         extends Closeable, Flushable
 {
     /**
-     * Allocates the next buffer for writing message packed data.
-     * If the previously allocated buffer is not flushed yet, this next method should discard
-     * it without writing it.
+     * Allocates the next buffer to write.
+     * 

+     * This method should return a MessageBuffer instance that has at least specified size of capacity.
+     * 

+     * When this method is called twice, the previously returned buffer is no longer used. This method may be called
+     * twice without call of {@link writeBuffer(MessageBuffer)} in between. In this case, the buffer should be
+     * discarded without flushing it to the output.
      *
      * @param minimumSize the mimium required buffer size to allocate
-     * @return
+     * @return the MessageBuffer instance with at least minimumSize bytes of capacity
      * @throws IOException
      */
     MessageBuffer next(int minimumSize)
             throws IOException;
 
     /**
-     * Flushes the previously allocated buffer.
-     * This method is not always called because next method also flushes previously allocated buffer.
-     * This method is called when write method is called or application wants to control the timing of flush.
+     * Writes the previously allocated buffer.
+     * 

+     * This method should write the buffer previously returned from {@link next(int)} method until specified number of
+     * bytes. Once the buffer is written, the buffer is no longer used.
+     * 

+     * This method is not always called for each {@link next(int)} call. In this case, the buffer should be discarded
+     * without flushing it to the output.
      *
-     * @param length the size of buffer to flush
+     * @param length the number of bytes to write
      * @throws IOException
      */
     void writeBuffer(int length)
@@ -63,7 +74,10 @@ void write(byte[] buffer, int offset, int length)
 
     /**
      * Writes an external payload data.
-     * This buffer is given - this MessageBufferOutput owns the buffer and may modify contents of the buffer. Contents of this buffer won't be modified by the caller.
+     * 

+     * Unlike {@link #write(byte[], int, int)} method, the buffer is given - this MessageBufferOutput implementation
+     * gets ownership of the buffer and may modify contents of the buffer. Contents of this buffer won't be modified
+     * by the caller.
      *
      * @param buffer the data to add
      * @param offset the start offset in the data
diff --git a/msgpack-core/src/main/java/org/msgpack/value/ArrayValue.java b/msgpack-core/src/main/java/org/msgpack/value/ArrayValue.java
index 4d7a6e8c2..05d64d3d7 100644
--- a/msgpack-core/src/main/java/org/msgpack/value/ArrayValue.java
+++ b/msgpack-core/src/main/java/org/msgpack/value/ArrayValue.java
@@ -19,7 +19,7 @@
 import java.util.List;
 
 /**
- * The interface {@code ArrayValue} represents MessagePack's Array type.
+ * Representation of MessagePack's Array type.
  *
  * MessagePack's Array type can represent sequence of values.
  */
diff --git a/msgpack-core/src/main/java/org/msgpack/value/BinaryValue.java b/msgpack-core/src/main/java/org/msgpack/value/BinaryValue.java
index c66f7a67c..74a413316 100644
--- a/msgpack-core/src/main/java/org/msgpack/value/BinaryValue.java
+++ b/msgpack-core/src/main/java/org/msgpack/value/BinaryValue.java
@@ -16,7 +16,7 @@
 package org.msgpack.value;
 
 /**
- * The interface {@code BinaryValue} represents MessagePack's Binary type.
+ * Representation of MessagePack's Binary type.
  *
  * MessagePack's Binary type can represent a byte array at most 264-1 bytes.
  *
diff --git a/msgpack-core/src/main/java/org/msgpack/value/BooleanValue.java b/msgpack-core/src/main/java/org/msgpack/value/BooleanValue.java
index 6ccf5c9ef..b0aa3b9d8 100644
--- a/msgpack-core/src/main/java/org/msgpack/value/BooleanValue.java
+++ b/msgpack-core/src/main/java/org/msgpack/value/BooleanValue.java
@@ -16,7 +16,7 @@
 package org.msgpack.value;
 
 /**
- * The interface {@code BooleanValue} represents MessagePack's Boolean type.
+ * Representation MessagePack's Boolean type.
  *
  * MessagePack's Boolean type can represent {@code true} or {@code false}.
  */
diff --git a/msgpack-core/src/main/java/org/msgpack/value/ExtensionValue.java b/msgpack-core/src/main/java/org/msgpack/value/ExtensionValue.java
index 5a076ecbc..51c50b9a8 100644
--- a/msgpack-core/src/main/java/org/msgpack/value/ExtensionValue.java
+++ b/msgpack-core/src/main/java/org/msgpack/value/ExtensionValue.java
@@ -16,7 +16,7 @@
 package org.msgpack.value;
 
 /**
- * The interface {@code ExtensionValue} represents MessagePack's Extension type.
+ * Representation of MessagePack's Extension type.
  *
  * MessagePack's Extension type can represent represents a tuple of type information and a byte array where type information is an
  * integer whose meaning is defined by applications.
diff --git a/msgpack-core/src/main/java/org/msgpack/value/FloatValue.java b/msgpack-core/src/main/java/org/msgpack/value/FloatValue.java
index dbaf73a18..68fcf9fa5 100644
--- a/msgpack-core/src/main/java/org/msgpack/value/FloatValue.java
+++ b/msgpack-core/src/main/java/org/msgpack/value/FloatValue.java
@@ -16,7 +16,7 @@
 package org.msgpack.value;
 
 /**
- * The interface {@code FloatValue} represents MessagePack's Float type.
+ * Representation of MessagePack's Float type.
  *
  * MessagePack's Float type can represent IEEE 754 double precision floating point numbers including NaN and infinity. This is same with Java's {@code double} type.
  *
diff --git a/msgpack-core/src/main/java/org/msgpack/value/ImmutableArrayValue.java b/msgpack-core/src/main/java/org/msgpack/value/ImmutableArrayValue.java
index 9301c2eb8..9aa0687fa 100644
--- a/msgpack-core/src/main/java/org/msgpack/value/ImmutableArrayValue.java
+++ b/msgpack-core/src/main/java/org/msgpack/value/ImmutableArrayValue.java
@@ -18,6 +18,11 @@
 import java.util.Iterator;
 import java.util.List;
 
+/**
+ * Immutable representation of MessagePack's Array type.
+ *
+ * MessagePack's Array type can represent sequence of values.
+ */
 public interface ImmutableArrayValue
         extends ArrayValue, ImmutableValue
 {
diff --git a/msgpack-core/src/main/java/org/msgpack/value/ImmutableBinaryValue.java b/msgpack-core/src/main/java/org/msgpack/value/ImmutableBinaryValue.java
index 475241a57..9aefd7bc8 100644
--- a/msgpack-core/src/main/java/org/msgpack/value/ImmutableBinaryValue.java
+++ b/msgpack-core/src/main/java/org/msgpack/value/ImmutableBinaryValue.java
@@ -15,6 +15,13 @@
 //
 package org.msgpack.value;
 
+/**
+ * Immutable representation of MessagePack's Binary type.
+ *
+ * MessagePack's Binary type can represent a byte array at most 264-1 bytes.
+ *
+ * @see org.msgpack.value.ImmutableRawValue
+ */
 public interface ImmutableBinaryValue
         extends BinaryValue, ImmutableRawValue
 {
diff --git a/msgpack-core/src/main/java/org/msgpack/value/ImmutableBooleanValue.java b/msgpack-core/src/main/java/org/msgpack/value/ImmutableBooleanValue.java
index dd2afad43..dcf221171 100644
--- a/msgpack-core/src/main/java/org/msgpack/value/ImmutableBooleanValue.java
+++ b/msgpack-core/src/main/java/org/msgpack/value/ImmutableBooleanValue.java
@@ -15,6 +15,11 @@
 //
 package org.msgpack.value;
 
+/**
+ * Immutable representation of MessagePack's Boolean type.
+ *
+ * MessagePack's Boolean type can represent {@code true} or {@code false}.
+ */
 public interface ImmutableBooleanValue
         extends BooleanValue, ImmutableValue
 {
diff --git a/msgpack-core/src/main/java/org/msgpack/value/ImmutableExtensionValue.java b/msgpack-core/src/main/java/org/msgpack/value/ImmutableExtensionValue.java
index 5e984db05..8c9b73753 100644
--- a/msgpack-core/src/main/java/org/msgpack/value/ImmutableExtensionValue.java
+++ b/msgpack-core/src/main/java/org/msgpack/value/ImmutableExtensionValue.java
@@ -15,6 +15,11 @@
 //
 package org.msgpack.value;
 
+/**
+ * Immutable representation of MessagePack's Extension type.
+ *
+ * @see org.msgpack.value.ExtensionValue
+ */
 public interface ImmutableExtensionValue
         extends ExtensionValue, ImmutableValue
 {
diff --git a/msgpack-core/src/main/java/org/msgpack/value/ImmutableFloatValue.java b/msgpack-core/src/main/java/org/msgpack/value/ImmutableFloatValue.java
index 7105483d1..9a30f9b9f 100644
--- a/msgpack-core/src/main/java/org/msgpack/value/ImmutableFloatValue.java
+++ b/msgpack-core/src/main/java/org/msgpack/value/ImmutableFloatValue.java
@@ -15,6 +15,13 @@
 //
 package org.msgpack.value;
 
+/**
+ * Immutable representation of MessagePack's Float type.
+ *
+ * MessagePack's Float type can represent IEEE 754 double precision floating point numbers including NaN and infinity. This is same with Java's {@code double} type.
+ *
+ * @see org.msgpack.value.ImmutableNumberValue
+ */
 public interface ImmutableFloatValue
         extends FloatValue, ImmutableNumberValue
 {
diff --git a/msgpack-core/src/main/java/org/msgpack/value/ImmutableIntegerValue.java b/msgpack-core/src/main/java/org/msgpack/value/ImmutableIntegerValue.java
index 3482583ff..ec246748e 100644
--- a/msgpack-core/src/main/java/org/msgpack/value/ImmutableIntegerValue.java
+++ b/msgpack-core/src/main/java/org/msgpack/value/ImmutableIntegerValue.java
@@ -15,6 +15,11 @@
 //
 package org.msgpack.value;
 
+/**
+ * Immutable representation of MessagePack's Integer type.
+ *
+ * MessagePack's Integer type can represent from -263 to 264-1.
+ */
 public interface ImmutableIntegerValue
         extends IntegerValue, ImmutableNumberValue
 {
diff --git a/msgpack-core/src/main/java/org/msgpack/value/ImmutableMapValue.java b/msgpack-core/src/main/java/org/msgpack/value/ImmutableMapValue.java
index cc3122f03..0c27d5540 100644
--- a/msgpack-core/src/main/java/org/msgpack/value/ImmutableMapValue.java
+++ b/msgpack-core/src/main/java/org/msgpack/value/ImmutableMapValue.java
@@ -15,6 +15,11 @@
 //
 package org.msgpack.value;
 
+/**
+ * Immutable representation of MessagePack's Map type.
+ *
+ * MessagePack's Map type can represent sequence of key-value pairs.
+ */
 public interface ImmutableMapValue
         extends MapValue, ImmutableValue
 {
diff --git a/msgpack-core/src/main/java/org/msgpack/value/ImmutableNilValue.java b/msgpack-core/src/main/java/org/msgpack/value/ImmutableNilValue.java
index 8a7857287..36135fcef 100644
--- a/msgpack-core/src/main/java/org/msgpack/value/ImmutableNilValue.java
+++ b/msgpack-core/src/main/java/org/msgpack/value/ImmutableNilValue.java
@@ -15,6 +15,9 @@
 //
 package org.msgpack.value;
 
+/**
+ * Immutable representation of MessagePack's Nil type.
+ */
 public interface ImmutableNilValue
         extends NilValue, ImmutableValue
 {
diff --git a/msgpack-core/src/main/java/org/msgpack/value/ImmutableNumberValue.java b/msgpack-core/src/main/java/org/msgpack/value/ImmutableNumberValue.java
index 42afcf304..0ecd5bb36 100644
--- a/msgpack-core/src/main/java/org/msgpack/value/ImmutableNumberValue.java
+++ b/msgpack-core/src/main/java/org/msgpack/value/ImmutableNumberValue.java
@@ -15,6 +15,12 @@
 //
 package org.msgpack.value;
 
+/**
+ * Immutable base interface of {@link ImmutableIntegerValue} and {@link ImmutableFloatValue} interfaces. To extract primitive type values, call toXXX methods, which may lose some information by rounding or truncation.
+ *
+ * @see org.msgpack.value.immutableIntegerValue
+ * @see org.msgpack.value.immutableFloatValue
+ */
 public interface ImmutableNumberValue
         extends NumberValue, ImmutableValue
 {
diff --git a/msgpack-core/src/main/java/org/msgpack/value/ImmutableRawValue.java b/msgpack-core/src/main/java/org/msgpack/value/ImmutableRawValue.java
index 36698dbeb..d3f2eaab6 100644
--- a/msgpack-core/src/main/java/org/msgpack/value/ImmutableRawValue.java
+++ b/msgpack-core/src/main/java/org/msgpack/value/ImmutableRawValue.java
@@ -15,6 +15,14 @@
 //
 package org.msgpack.value;
 
+/**
+ * Immutable base interface of {@link ImmutableStringValue} and {@link ImmutableBinaryValue} interfaces.
+ * 

+ * MessagePack's Raw type can represent a byte array at most 264-1 bytes.
+ *
+ * @see org.msgpack.value.ImmutableStringValue
+ * @see org.msgpack.value.ImmutableBinaryValue
+ */
 public interface ImmutableRawValue
         extends RawValue, ImmutableValue
 {
diff --git a/msgpack-core/src/main/java/org/msgpack/value/ImmutableStringValue.java b/msgpack-core/src/main/java/org/msgpack/value/ImmutableStringValue.java
index 6e3f95360..2c198ae11 100644
--- a/msgpack-core/src/main/java/org/msgpack/value/ImmutableStringValue.java
+++ b/msgpack-core/src/main/java/org/msgpack/value/ImmutableStringValue.java
@@ -15,6 +15,12 @@
 //
 package org.msgpack.value;
 
+/**
+ * Immutable representation of MessagePack's String type.
+ *
+ * @see org.msgpack.value.StringValue
+ * @see org.msgpack.value.ImmutableRawValue
+ */
 public interface ImmutableStringValue
         extends StringValue, ImmutableRawValue
 {
diff --git a/msgpack-core/src/main/java/org/msgpack/value/ImmutableValue.java b/msgpack-core/src/main/java/org/msgpack/value/ImmutableValue.java
index 6a5740029..88798a13d 100644
--- a/msgpack-core/src/main/java/org/msgpack/value/ImmutableValue.java
+++ b/msgpack-core/src/main/java/org/msgpack/value/ImmutableValue.java
@@ -15,6 +15,9 @@
 //
 package org.msgpack.value;
 
+/**
+ * Immutable declaration of {@link Value} interface.
+ */
 public interface ImmutableValue
         extends Value
 {
diff --git a/msgpack-core/src/main/java/org/msgpack/value/IntegerValue.java b/msgpack-core/src/main/java/org/msgpack/value/IntegerValue.java
index 8480751c4..2776eb78c 100644
--- a/msgpack-core/src/main/java/org/msgpack/value/IntegerValue.java
+++ b/msgpack-core/src/main/java/org/msgpack/value/IntegerValue.java
@@ -20,7 +20,7 @@
 import java.math.BigInteger;
 
 /**
- * The interface {@code IntegerValue} represents MessagePack's Integer type.
+ * Representation of MessagePack's Integer type.
  *
  * MessagePack's Integer type can represent from -263 to 264-1.
  */
diff --git a/msgpack-core/src/main/java/org/msgpack/value/MapValue.java b/msgpack-core/src/main/java/org/msgpack/value/MapValue.java
index fa7f55c8d..a68982a47 100644
--- a/msgpack-core/src/main/java/org/msgpack/value/MapValue.java
+++ b/msgpack-core/src/main/java/org/msgpack/value/MapValue.java
@@ -20,7 +20,7 @@
 import java.util.Set;
 
 /**
- * The interface {@code ArrayValue} represents MessagePack's Map type.
+ * Representation of MessagePack's Map type.
  *
  * MessagePack's Map type can represent sequence of key-value pairs.
  */
diff --git a/msgpack-core/src/main/java/org/msgpack/value/NilValue.java b/msgpack-core/src/main/java/org/msgpack/value/NilValue.java
index 8f5835001..9307ae6f0 100644
--- a/msgpack-core/src/main/java/org/msgpack/value/NilValue.java
+++ b/msgpack-core/src/main/java/org/msgpack/value/NilValue.java
@@ -16,7 +16,7 @@
 package org.msgpack.value;
 
 /**
- * The interface {@code NilValue} represents MessagePack's Nil type.
+ * Representation of MessagePack's Nil type.
  */
 public interface NilValue
         extends Value
diff --git a/msgpack-core/src/main/java/org/msgpack/value/NumberValue.java b/msgpack-core/src/main/java/org/msgpack/value/NumberValue.java
index 3e5bd75e0..828e6353c 100644
--- a/msgpack-core/src/main/java/org/msgpack/value/NumberValue.java
+++ b/msgpack-core/src/main/java/org/msgpack/value/NumberValue.java
@@ -18,7 +18,7 @@
 import java.math.BigInteger;
 
 /**
- * The base interface {@code NumberValue} of {@code IntegerValue} and {@code FloatValue}. To extract primitive type values, call toXXX methods, which may lose some information by rounding or truncation.
+ * Base interface of {@link IntegerValue} and {@link FloatValue} interfaces. To extract primitive type values, call toXXX methods, which may lose some information by rounding or truncation.
  *
  * @see org.msgpack.value.IntegerValue
  * @see org.msgpack.value.FloatValue
diff --git a/msgpack-core/src/main/java/org/msgpack/value/RawValue.java b/msgpack-core/src/main/java/org/msgpack/value/RawValue.java
index 8857b5340..9ce62463f 100644
--- a/msgpack-core/src/main/java/org/msgpack/value/RawValue.java
+++ b/msgpack-core/src/main/java/org/msgpack/value/RawValue.java
@@ -18,7 +18,7 @@
 import java.nio.ByteBuffer;
 
 /**
- * The interface {@code RawValue} represents MessagePack's Raw type, which means Binary or String type.
+ * Base interface of {@link StringValue} and {@link BinaryValue} interfaces.
  * 

  * MessagePack's Raw type can represent a byte array at most 264-1 bytes.
  *
diff --git a/msgpack-core/src/main/java/org/msgpack/value/StringValue.java b/msgpack-core/src/main/java/org/msgpack/value/StringValue.java
index 0c812d58d..de2ec1eae 100644
--- a/msgpack-core/src/main/java/org/msgpack/value/StringValue.java
+++ b/msgpack-core/src/main/java/org/msgpack/value/StringValue.java
@@ -16,7 +16,7 @@
 package org.msgpack.value;
 
 /**
- * The interface {@code StringValue} represents MessagePack's String type.
+ * Representation of MessagePack's String type.
  *
  * MessagePack's String type can represent a UTF-8 string at most 264-1 bytes.
  *
diff --git a/msgpack-core/src/main/java/org/msgpack/value/Value.java b/msgpack-core/src/main/java/org/msgpack/value/Value.java
index 2fae838b4..546dfbbf4 100644
--- a/msgpack-core/src/main/java/org/msgpack/value/Value.java
+++ b/msgpack-core/src/main/java/org/msgpack/value/Value.java
@@ -20,11 +20,60 @@
 import java.io.IOException;
 
 /**
- * Value is an implementation of MessagePack type system. To retrieve values from a Value object,
- * You need to check its {@link ValueType} then call an appropriate asXXXValue method.
+ * Value stores a value and its type in MessagePack type system.
  *
+ * 
Type conversion

+ * 

+ * You can check type first using isXxx() methods or {@link #getValueType()} method, then convert the value to a
+ * subtype using asXxx() methods. You can also call asXxx() methods directly and catch
+ * {@link org.msgpack.core.MessageTypeCastException}.
  *
+ * 
+ *   
+ *   
+ *   
+ *   
+ *   
+ *   
+ *   
+ *   
+ *   
+ *   
+ *   
+ *   
+ * 
MessagePack typeCheck methodConvert methodValue type
Nil{@link #isNilValue()}{@link #asNumberValue()}{@link NilValue}
Boolean{@link #isBooleanValue()}{@link #asBooleanValue()}{@link BooleanValue}
Integer or Float{@link #isNumberValue()}{@link #asNumberValue()}{@link NumberValue}
Integer{@link #isIntegerValue()}{@link #asIntegerValue()}{@link IntegerValue}
Float{@link #isFloatValue()}{@link #asFloatValue()}{@link FloatValue}
String or Binary{@link #isRawValue()}{@link #asRawValue()}{@link RawValue}
String{@link #isStringValue()}{@link #asStringValue()}{@link StringValue}
Binary{@link #isBinaryValue()}{@link #asBinaryValue()}{@link BinaryValue}
Array{@link #isArrayValue()}{@link #asArrayValue()}{@link ArrayValue}
Map{@link #isMapValue()}{@link #asMapValue()}{@link MapValue}
Extension{@link #isExtensionValue()}{@link #asExtensionValue()}{@link ExtensionValue}

  *
+ * 
Immutable interface

+ * 

+ * Value interface is the base interface of all Value interfaces. Immutable subtypes are useful so that you can
+ * declare that a (final) field or elements of a container object are immutable. Method arguments should be a
+ * regular Value interface generally.
+ * 

+ * You can use {@link #immutableValue()} method to get immutable subtypes.
+ *
+ * 
+ *   
+ *   
+ *   
+ *   
+ *   
+ *   
+ *   
+ *   
+ *   
+ *   
+ *   
+ *   
+ *   
+ * 
MessagePack typeSubtype methodImmutable value type
any types{@link Value}.{@link Value#immutableValue()}{@link ImmutableValue}
Nil{@link NilValue}.{@link NilValue#immutableValue()}{@link ImmutableNilValue}
Boolean{@link BooleanValue}.{@link BooleanValue#immutableValue()}{@link ImmutableBooleanValue}
Integer{@link IntegerValue}.{@link IntegerValue#immutableValue()}{@link ImmutableIntegerValue}
Float{@link FloatValue}.{@link FloatValue#immutableValue()}{@link ImmutableFloatValue}
Integer or Float{@link NumberValue}.{@link NumberValue#immutableValue()}{@link ImmutableNumberValue}
String or Binary{@link RawValue}.{@link RawValue#immutableValue()}{@link ImmutableRawValue}
String{@link StringValue}.{@link StringValue#immutableValue()}{@link ImmutableStringValue}
Binary{@link BinaryValue}.{@link BinaryValue#immutableValue()}{@link ImmutableBinaryValue}
Array{@link ArrayValue}.{@link ArrayValue#immutableValue()}{@link ImmutableArrayValue}
Map{@link MapValue}.{@link MapValue#immutableValue()}{@link ImmutableMapValue}
Extension{@link ExtensionValue}.{@link ExtensionValue#immutableValue()}{@link ImmutableExtensionValue}

+ *
+ * 
Converting to JSON

+ * 

+ * {@link #toJson()} method returns JSON representation of a Value. See its documents for details.
+ * 

+ * toString() also returns a string representation of a Value that is similar to JSON. However, unlike toJson() method,
+ * toString() may return a special format that is not be compatible with JSON when JSON doesn't support the type such
+ * as ExtensionValue.
  */
 public interface Value
 {
@@ -249,14 +298,16 @@ void writeTo(MessagePacker pk)
 
     /**
      * Returns json representation of this Value.
-     *
+     * 

      * Following behavior is not configurable at this release and they might be changed at future releases:
      *
-     * * if a key of MapValue is not string, the key is converted to a string using toString method.
-     * * NaN and Infinity of DoubleValue are converted to null.
-     * * ExtensionValue is converted to a 2-element array where first element is a number and second element is the data encoded in hex.
-     * * BinaryValue is converted to a string using UTF-8 encoding. Invalid byte sequence is replaced with U+FFFD replacement character.
-     * * Invalid UTF-8 byte sequences in StringValue is replaced with U+FFFD replacement character
+     * 
    
+     * 
  • if a key of MapValue is not string, the key is converted to a string using toString method.
    • 
+     * 
  • NaN and Infinity of DoubleValue are converted to null.
    • 
+     * 
  • ExtensionValue is converted to a 2-element array where first element is a number and second element is the data encoded in hex.
    • 
+     * 
  • BinaryValue is converted to a string using UTF-8 encoding. Invalid byte sequence is replaced with U+FFFD replacement character.
    • 
+     * 
  • Invalid UTF-8 byte sequences in StringValue is replaced with U+FFFD replacement character
    • 
+     * 
      
      */
     String toJson();
 }
diff --git a/msgpack-core/src/main/java/org/msgpack/value/ValueType.java b/msgpack-core/src/main/java/org/msgpack/value/ValueType.java
index 91b2a585f..b06936697 100644
--- a/msgpack-core/src/main/java/org/msgpack/value/ValueType.java
+++ b/msgpack-core/src/main/java/org/msgpack/value/ValueType.java
@@ -16,7 +16,13 @@
 package org.msgpack.value;
 
 /**
- * MessageTypeFamily is a group of {@link org.msgpack.core.MessageFormat}s
+ * Representation of MessagePack types.
+ * 
      
+ * MessagePack uses hierarchical type system. Integer and Float are subypte of Number, Thus {@link isNumberType()}
+ * returns true if type is Integer or Float. String and Binary are subtype of Raw. Thus {@link isRawType()} returns
+ * true if type is String or Binary.
+ *
+ * @see org.msgpack.core.MessageFormat
  */
 public enum ValueType
 {

From 462c2a04b796e10f3784639d48fa67d92eaf3fea Mon Sep 17 00:00:00 2001
From: Sadayuki Furuhashi 
Date: Wed, 26 Oct 2016 10:12:56 -0700
Subject: [PATCH 3/5] docs: minor fixes

---
 .../main/java/org/msgpack/core/buffer/MessageBuffer.java | 9 +++++----
 .../org/msgpack/core/buffer/MessageBufferOutput.java     | 4 ++--
 2 files changed, 7 insertions(+), 6 deletions(-)

diff --git a/msgpack-core/src/main/java/org/msgpack/core/buffer/MessageBuffer.java b/msgpack-core/src/main/java/org/msgpack/core/buffer/MessageBuffer.java
index 65cb6eba3..05eccbfce 100644
--- a/msgpack-core/src/main/java/org/msgpack/core/buffer/MessageBuffer.java
+++ b/msgpack-core/src/main/java/org/msgpack/core/buffer/MessageBuffer.java
@@ -38,9 +38,9 @@
  * 
      
  * MessageBuffer class itself is optimized for little-endian CPU archtectures so that JVM (HotSpot) can take advantage
  * of the fastest JIT format which skips TypeProfile checking. To ensure this performance, applications must not load
- * unnecessary classes such as MessagePackBE. On big-endian CPU archtectures, implementation uses subclass that
- * includes TypeProfile overhead but still faster than ByteBuffer. On JVMs older than Java 7 and JVMs without Unsafe
- * API (such as Android), implementation falls back to a universal implementation that uses standard ByteBuffer class
+ * unnecessary classes such as MessagePackBE. On big-endian CPU archtectures, it automatically uses a subclass that
+ * includes TypeProfile overhead but still faster than stndard ByteBuffer class. On JVMs older than Java 7 and JVMs
+ * without Unsafe API (such as Android), implementation falls back to an universal implementation that uses ByteBuffer
  * internally.
  */
 public class MessageBuffer
@@ -77,7 +77,8 @@ public class MessageBuffer
                 try {
                     int major = Integer.parseInt(javaVersion.substring(0, dotPos));
                     int minor = Integer.parseInt(javaVersion.substring(dotPos + 1));
-                    isJavaAtLeast7 = major > 1 || (major == 1 && minor >= 7); }
+                    isJavaAtLeast7 = major > 1 || (major == 1 && minor >= 7);
+                }
                 catch (NumberFormatException e) {
                     e.printStackTrace(System.err);
                 }
diff --git a/msgpack-core/src/main/java/org/msgpack/core/buffer/MessageBufferOutput.java b/msgpack-core/src/main/java/org/msgpack/core/buffer/MessageBufferOutput.java
index 9ae1b13dd..66a5c43ea 100644
--- a/msgpack-core/src/main/java/org/msgpack/core/buffer/MessageBufferOutput.java
+++ b/msgpack-core/src/main/java/org/msgpack/core/buffer/MessageBufferOutput.java
@@ -31,7 +31,7 @@ public interface MessageBufferOutput
     /**
      * Allocates the next buffer to write.
      * 
      
-     * This method should return a MessageBuffer instance that has at least specified size of capacity.
+     * This method should return a MessageBuffer instance that has specified size of capacity at least.
      * 
      
      * When this method is called twice, the previously returned buffer is no longer used. This method may be called
      * twice without call of {@link writeBuffer(MessageBuffer)} in between. In this case, the buffer should be
@@ -51,7 +51,7 @@ MessageBuffer next(int minimumSize)
      * bytes. Once the buffer is written, the buffer is no longer used.
      * 
      
      * This method is not always called for each {@link next(int)} call. In this case, the buffer should be discarded
-     * without flushing it to the output.
+     * without flushing it to the output when the next {@link next(int)} is called.
      *
      * @param length the number of bytes to write
      * @throws IOException

From 629f8052027dc00ac0d564240a4c96604694a6f1 Mon Sep 17 00:00:00 2001
From: Sadayuki Furuhashi 
Date: Wed, 26 Oct 2016 10:25:17 -0700
Subject: [PATCH 4/5] docs: fixes warnings

---
 .../java/org/msgpack/core/MessagePacker.java  | 22 ++++++++++---------
 .../org/msgpack/core/MessageUnpacker.java     |  7 +++---
 .../msgpack/core/buffer/MessageBuffer.java    | 15 ++++++++-----
 .../core/buffer/MessageBufferInput.java       |  2 +-
 .../core/buffer/MessageBufferOutput.java      | 10 ++++-----
 .../msgpack/value/ImmutableNumberValue.java   |  4 ++--
 .../java/org/msgpack/value/IntegerValue.java  |  3 ++-
 .../main/java/org/msgpack/value/RawValue.java |  2 +-
 .../java/org/msgpack/value/ValueType.java     |  4 ++--
 9 files changed, 36 insertions(+), 33 deletions(-)

diff --git a/msgpack-core/src/main/java/org/msgpack/core/MessagePacker.java b/msgpack-core/src/main/java/org/msgpack/core/MessagePacker.java
index 0c61b4bd1..3a6627f71 100644
--- a/msgpack-core/src/main/java/org/msgpack/core/MessagePacker.java
+++ b/msgpack-core/src/main/java/org/msgpack/core/MessagePacker.java
@@ -447,7 +447,7 @@ else if (v < (1 << 7)) {
      * 
      
      * This method writes an integer using the smallest format from the int format family.
      *
-     * @param v the integer to be written
+     * @param r the integer to be written
      * @return this
      * @throws IOException when underlaying output throws IOException
      */
@@ -570,7 +570,7 @@ else if (bi.bitLength() == 64 && bi.signum() == 1) {
      * 
      
      * This method writes a float value using float format family.
      *
-     * @param bi the integer to be written
+     * @param v the value to be written
      * @return this
      * @throws IOException when underlaying output throws IOException
      */
@@ -587,7 +587,7 @@ public MessagePacker packFloat(float v)
      * 
      
      * This method writes a float value using float format family.
      *
-     * @param bi the integer to be written
+     * @param v the value to be written
      * @return this
      * @throws IOException when underlaying output throws IOException
      */
@@ -826,7 +826,8 @@ public MessagePacker packValue(Value v)
      * 
      
      * You will call {@link #writePayload(byte[])} or {@link #addPayload(byte[])} method to write body binary.
      *
-     * @param len number of bytes of a payload binary to be written
+     * @param extType the extension type tag to be written
+     * @param payloadLen number of bytes of a payload binary to be written
      * @return this
      * @throws IOException when underlaying output throws IOException
      */
@@ -972,9 +973,9 @@ public MessagePacker writePayload(byte[] src, int off, int len)
     /**
      * Writes a byte array to the output.
      * 
      
-     * Unlike {@link #writePayload} method, this method doesn't copy the byte array even when given byte array
-     * is shorter than {@link MessagePack.PackerConfig#withBufferFlushThreshold(int)}. This is faster than
-     * {@link writePayload} method but caller must not modify the byte array after calling this method.
+     * Unlike {@link #writePayload(byte[])} method, this method doesn't copy the byte array even when given byte
+     * array is shorter than {@link MessagePack.PackerConfig#withBufferFlushThreshold(int)}. This is faster than
+     * {@link #writePayload(byte[])} method but caller must not modify the byte array after calling this method.
      *
      * @param src the data to add
      * @return this
@@ -989,9 +990,10 @@ public MessagePacker addPayload(byte[] src)
     /**
      * Writes a byte array to the output.
      * 
      
-     * Unlike {@link #writePayload} method, this method doesn't copy the byte array even when given byte array
-     * is shorter than {@link MessagePack.PackerConfig#withBufferFlushThreshold(int)}. This is faster than
-     * {@link writePayload} method but caller must not modify the byte array after calling this method.
+     * Unlike {@link #writePayload(byte[], int, int)} method, this method doesn't copy the byte array even when
+     * given byte array is shorter than {@link MessagePack.PackerConfig#withBufferFlushThreshold(int)}.
+     * This is faster than {@link #writePayload(byte[], int, int)} method but caller must not modify the byte array
+     * after calling this method.
      *
      * @param src the data to add
      * @param off the start offset in the data
diff --git a/msgpack-core/src/main/java/org/msgpack/core/MessageUnpacker.java b/msgpack-core/src/main/java/org/msgpack/core/MessageUnpacker.java
index 64d26a29f..99a42a5fb 100644
--- a/msgpack-core/src/main/java/org/msgpack/core/MessageUnpacker.java
+++ b/msgpack-core/src/main/java/org/msgpack/core/MessageUnpacker.java
@@ -47,7 +47,7 @@
  * 
      
  * One use case is to read objects as {@link Value} using {@link #unpackValue} method. A {@link Value} object
  * contains type of the deserialized value as well as the value itself so that you can inspect type of the
- * deserialized values later. You can repeat {@link #unpackValue} until {@link hasNext()} method returns false so
+ * deserialized values later. You can repeat {@link #unpackValue} until {@link #hasNext()} method returns false so
  * that you can deserialize sequence of MessagePack values.
  * 
      
  * The other use case is to use {@link #getNextFormat()} and {@link MessageFormat#getValueType()} methods followed
@@ -142,7 +142,7 @@
  * you call unpacker methods for each element.
  *
  * 
      
- * To read a Map, first you call {@link #unpackMapHeader(int)} method to get number of pairs of the map. Then,
+ * To read a Map, first you call {@link #unpackMapHeader()} method to get number of pairs of the map. Then,
  * for each pair, you call unpacker methods for key first, and then value. You will call unpacker methods twice
  * as many time as the returned count.
  *
@@ -228,7 +228,7 @@ protected MessageUnpacker(MessageBufferInput in, MessagePack.UnpackerConfig conf
      * 
      
      * This method doesn't close the old input.
      *
-     * @param out new input
+     * @param in new input
      * @return the old input
      * @throws IOException never happens unless a subclass overrides this method
      * @throws NullPointerException the given input is null
@@ -718,7 +718,6 @@ public Variable unpackValue(Variable var)
     /**
      * Reads a Nil byte.
      *
-     * @return the read value
      * @throws MessageTypeException when value is not MessagePack Nil type
      * @throws IOException when underlaying input throws IOException
      */
diff --git a/msgpack-core/src/main/java/org/msgpack/core/buffer/MessageBuffer.java b/msgpack-core/src/main/java/org/msgpack/core/buffer/MessageBuffer.java
index 05eccbfce..730cd245b 100644
--- a/msgpack-core/src/main/java/org/msgpack/core/buffer/MessageBuffer.java
+++ b/msgpack-core/src/main/java/org/msgpack/core/buffer/MessageBuffer.java
@@ -33,7 +33,7 @@
  * big-endian order.
  * 
      
  * Applications can allocate a new buffer using {@link #allocate(int)} method, or wrap an byte array or ByteBuffer
- * using {@link wrap(byte[], int, int)} methods. {@link wrap(ByteBuffer)} method supports both direct buffers and
+ * using {@link #wrap(byte[], int, int)} methods. {@link #wrap(ByteBuffer)} method supports both direct buffers and
  * array-backed buffers.
  * 
      
  * MessageBuffer class itself is optimized for little-endian CPU archtectures so that JVM (HotSpot) can take advantage
@@ -213,7 +213,7 @@ public static MessageBuffer allocate(int size)
      * The new buffer's size will be array.length. hasArray() will return true.
      *
      * @param array the byte array that will gack this MessageBuffer
-     * @return
+     * @return the new MessageBuffer
      *
      */
     public static MessageBuffer wrap(byte[] array)
@@ -231,7 +231,7 @@ public static MessageBuffer wrap(byte[] array)
      * @param array the byte array that will gack this MessageBuffer
      * @param offset The offset of the subarray to be used; must be non-negative and no larger than array.length
      * @param length The length of the subarray to be used; must be non-negative and no larger than array.length - offset
-     * @return
+     * @return the new MessageBuffer
      *
      */
     public static MessageBuffer wrap(byte[] array, int offset, int length)
@@ -249,7 +249,7 @@ public static MessageBuffer wrap(byte[] array, int offset, int length)
      * @param bb the byte buffer that will gack this MessageBuffer
      * @throws IllegalArgumentException given byte buffer returns false both from hasArray() and isDirect()
      * @throws UnsupportedOperationException given byte buffer is a direct buffer and this platform doesn't support Unsafe API
-     * @return
+     * @return the new MessageBuffer
      *
      */
     public static MessageBuffer wrap(ByteBuffer bb)
@@ -381,9 +381,12 @@ protected MessageBuffer(Object base, long address, int length)
     }
 
     /**
-     * byte size of the buffer
+     * Gets size of the buffer.
      *
-     * @return
+     * MessageBuffer doesn't have limit unlike ByteBuffer. Instead, you can use {@link #slice(int, int)} to get a
+     * part of the buffer.
+     *
+     * @return number of bytes
      */
     public int size()
     {
diff --git a/msgpack-core/src/main/java/org/msgpack/core/buffer/MessageBufferInput.java b/msgpack-core/src/main/java/org/msgpack/core/buffer/MessageBufferInput.java
index 2b19b9d99..77f7a06f6 100644
--- a/msgpack-core/src/main/java/org/msgpack/core/buffer/MessageBufferInput.java
+++ b/msgpack-core/src/main/java/org/msgpack/core/buffer/MessageBufferInput.java
@@ -43,7 +43,7 @@ MessageBuffer next()
     /**
      * Closes the input.
      * 
      
-     * When this method is called, the buffer previously returned from {@link next()} method is no longer used.
+     * When this method is called, the buffer previously returned from {@link #next()} method is no longer used.
      * Thus implementation of this method can safely discard it.
      * 
      
      * If the input is already closed then invoking this method has no effect.
diff --git a/msgpack-core/src/main/java/org/msgpack/core/buffer/MessageBufferOutput.java b/msgpack-core/src/main/java/org/msgpack/core/buffer/MessageBufferOutput.java
index 66a5c43ea..a9a51fbcc 100644
--- a/msgpack-core/src/main/java/org/msgpack/core/buffer/MessageBufferOutput.java
+++ b/msgpack-core/src/main/java/org/msgpack/core/buffer/MessageBufferOutput.java
@@ -34,7 +34,7 @@ public interface MessageBufferOutput
      * This method should return a MessageBuffer instance that has specified size of capacity at least.
      * 
      
      * When this method is called twice, the previously returned buffer is no longer used. This method may be called
-     * twice without call of {@link writeBuffer(MessageBuffer)} in between. In this case, the buffer should be
+     * twice without call of {@link #writeBuffer(int)} in between. In this case, the buffer should be
      * discarded without flushing it to the output.
      *
      * @param minimumSize the mimium required buffer size to allocate
@@ -47,11 +47,11 @@ MessageBuffer next(int minimumSize)
     /**
      * Writes the previously allocated buffer.
      * 
      
-     * This method should write the buffer previously returned from {@link next(int)} method until specified number of
+     * This method should write the buffer previously returned from {@link #next(int)} method until specified number of
      * bytes. Once the buffer is written, the buffer is no longer used.
      * 
      
-     * This method is not always called for each {@link next(int)} call. In this case, the buffer should be discarded
-     * without flushing it to the output when the next {@link next(int)} is called.
+     * This method is not always called for each {@link #next(int)} call. In this case, the buffer should be discarded
+     * without flushing it to the output when the next {@link #next(int)} is called.
      *
      * @param length the number of bytes to write
      * @throws IOException
@@ -66,7 +66,6 @@ void writeBuffer(int length)
      * @param buffer the data to write
      * @param offset the start offset in the data
      * @param length the number of bytes to write
-     * @return
      * @throws IOException
      */
     void write(byte[] buffer, int offset, int length)
@@ -82,7 +81,6 @@ void write(byte[] buffer, int offset, int length)
      * @param buffer the data to add
      * @param offset the start offset in the data
      * @param length the number of bytes to add
-     * @return
      * @throws IOException
      */
     void add(byte[] buffer, int offset, int length)
diff --git a/msgpack-core/src/main/java/org/msgpack/value/ImmutableNumberValue.java b/msgpack-core/src/main/java/org/msgpack/value/ImmutableNumberValue.java
index 0ecd5bb36..a3b984af6 100644
--- a/msgpack-core/src/main/java/org/msgpack/value/ImmutableNumberValue.java
+++ b/msgpack-core/src/main/java/org/msgpack/value/ImmutableNumberValue.java
@@ -18,8 +18,8 @@
 /**
  * Immutable base interface of {@link ImmutableIntegerValue} and {@link ImmutableFloatValue} interfaces. To extract primitive type values, call toXXX methods, which may lose some information by rounding or truncation.
  *
- * @see org.msgpack.value.immutableIntegerValue
- * @see org.msgpack.value.immutableFloatValue
+ * @see org.msgpack.value.ImmutableIntegerValue
+ * @see org.msgpack.value.ImmutableFloatValue
  */
 public interface ImmutableNumberValue
         extends NumberValue, ImmutableValue
diff --git a/msgpack-core/src/main/java/org/msgpack/value/IntegerValue.java b/msgpack-core/src/main/java/org/msgpack/value/IntegerValue.java
index 2776eb78c..b23378261 100644
--- a/msgpack-core/src/main/java/org/msgpack/value/IntegerValue.java
+++ b/msgpack-core/src/main/java/org/msgpack/value/IntegerValue.java
@@ -49,7 +49,8 @@ public interface IntegerValue
 
     /**
      * Returns the most succinct MessageFormat type to represent this integer value.
-     * @return
+     *
+     * @return the smallest integer type of MessageFormat that is big enough to store the value.
      */
     MessageFormat mostSuccinctMessageFormat();
 
diff --git a/msgpack-core/src/main/java/org/msgpack/value/RawValue.java b/msgpack-core/src/main/java/org/msgpack/value/RawValue.java
index 9ce62463f..ba327a835 100644
--- a/msgpack-core/src/main/java/org/msgpack/value/RawValue.java
+++ b/msgpack-core/src/main/java/org/msgpack/value/RawValue.java
@@ -38,7 +38,7 @@ public interface RawValue
     /**
      * Returns the value as {@code ByteBuffer}.
      *
-     * Returned ByteBuffer is read-only. See {@code#asReadOnlyBuffer()}.
+     * Returned ByteBuffer is read-only. See also {@link java.nio.ByteBuffer#asReadOnlyBuffer()}.
      * This method doesn't copy the byte array as much as possible.
      */
     ByteBuffer asByteBuffer();
diff --git a/msgpack-core/src/main/java/org/msgpack/value/ValueType.java b/msgpack-core/src/main/java/org/msgpack/value/ValueType.java
index b06936697..b06478402 100644
--- a/msgpack-core/src/main/java/org/msgpack/value/ValueType.java
+++ b/msgpack-core/src/main/java/org/msgpack/value/ValueType.java
@@ -18,8 +18,8 @@
 /**
  * Representation of MessagePack types.
  * 
      
- * MessagePack uses hierarchical type system. Integer and Float are subypte of Number, Thus {@link isNumberType()}
- * returns true if type is Integer or Float. String and Binary are subtype of Raw. Thus {@link isRawType()} returns
+ * MessagePack uses hierarchical type system. Integer and Float are subypte of Number, Thus {@link #isNumberType()}
+ * returns true if type is Integer or Float. String and Binary are subtype of Raw. Thus {@link #isRawType()} returns
  * true if type is String or Binary.
  *
  * @see org.msgpack.core.MessageFormat

From 49ed7abfde095ec46ff93ef5440e9320cefa4967 Mon Sep 17 00:00:00 2001
From: Sadayuki Furuhashi 
Date: Sat, 26 Nov 2016 16:30:10 -0800
Subject: [PATCH 5/5] applied review comments to javadoc

---
 .../org/msgpack/core/MessageBufferPacker.java |  6 +-
 .../java/org/msgpack/core/MessagePacker.java  | 62 +++++++++----------
 .../org/msgpack/core/MessageUnpacker.java     | 62 +++++++++----------
 .../core/buffer/ArrayBufferOutput.java        |  4 +-
 .../msgpack/core/buffer/MessageBuffer.java    | 12 ++--
 5 files changed, 73 insertions(+), 73 deletions(-)

diff --git a/msgpack-core/src/main/java/org/msgpack/core/MessageBufferPacker.java b/msgpack-core/src/main/java/org/msgpack/core/MessageBufferPacker.java
index 3f6b732a1..38962dbe2 100644
--- a/msgpack-core/src/main/java/org/msgpack/core/MessageBufferPacker.java
+++ b/msgpack-core/src/main/java/org/msgpack/core/MessageBufferPacker.java
@@ -78,7 +78,7 @@ public byte[] toByteArray()
             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();
@@ -98,7 +98,7 @@ public MessageBuffer toMessageBuffer()
             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();
@@ -118,7 +118,7 @@ public List toBufferList()
             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();
diff --git a/msgpack-core/src/main/java/org/msgpack/core/MessagePacker.java b/msgpack-core/src/main/java/org/msgpack/core/MessagePacker.java
index 3a6627f71..1cd9a9801 100644
--- a/msgpack-core/src/main/java/org/msgpack/core/MessagePacker.java
+++ b/msgpack-core/src/main/java/org/msgpack/core/MessagePacker.java
@@ -72,7 +72,7 @@
  * an instance.
  * 
      
  * This class provides following primitive methods to write MessagePack values. These primitive methods write
- * short bytes (1 to 7 bytes) to the internal buffer at once. There are also some complex methods for convenience.
+ * short bytes (1 to 7 bytes) to the internal buffer at once. There are also some utility methods for convenience.
  * 
      
  * Primitive methods:
  *
@@ -95,7 +95,7 @@
  * 
  *
  * 
      
- * Complex methods:
+ * Utility methods:
  *
  * 
  *   
@@ -173,7 +173,7 @@ protected MessagePacker(MessageBufferOutput out, MessagePack.PackerConfig config
     }
 
     /**
-     * Replaces underlaying output.
+     * Replaces underlying output.
      * 
      
      * This method flushes current internal buffer to the output, swaps it with the new given output, then returns
      * the old output.
@@ -183,7 +183,7 @@ protected MessagePacker(MessageBufferOutput out, MessagePack.PackerConfig config
      *
      * @param out new output
      * @return the old output
-     * @throws IOException when underlaying output throws IOException
+     * @throws IOException when underlying output throws IOException
      * @throws NullPointerException the given output is null
      */
     public MessageBufferOutput reset(MessageBufferOutput out)
@@ -206,7 +206,7 @@ public MessageBufferOutput reset(MessageBufferOutput out)
     /**
      * Returns total number of written bytes.
      * 
      
-     * This method returns total of amount of data flushed to the underlaying output plus size of current
+     * This method returns total of amount of data flushed to the underlying output plus size of current
      * internal buffer.
      *
      * 
      
@@ -218,9 +218,9 @@ public long getTotalWrittenBytes()
     }
 
     /**
-     * Flushes internal buffer to the underlaying output.
+     * Flushes internal buffer to the underlying output.
      * 
      
-     * This method also calls flush method of the underlaying output after writing internal buffer.
+     * This method also calls flush method of the underlying output after writing internal buffer.
      */
     @Override
     public void flush()
@@ -233,7 +233,7 @@ public void flush()
     }
 
     /**
-     * Closes underlaying output.
+     * Closes underlying output.
      * 
      
      * This method flushes internal buffer before closing.
      */
@@ -360,7 +360,7 @@ private void writeLong(long v)
      * This method writes a nil byte.
      *
      * @return this
-     * @throws IOException when underlaying output throws IOException
+     * @throws IOException when underlying output throws IOException
      */
     public MessagePacker packNil()
             throws IOException
@@ -375,7 +375,7 @@ public MessagePacker packNil()
      * This method writes a true byte or a false byte.
      *
      * @return this
-     * @throws IOException when underlaying output throws IOException
+     * @throws IOException when underlying output throws IOException
      */
     public MessagePacker packBoolean(boolean b)
             throws IOException
@@ -392,7 +392,7 @@ public MessagePacker packBoolean(boolean b)
      *
      * @param b the integer to be written
      * @return this
-     * @throws IOException when underlaying output throws IOException
+     * @throws IOException when underlying output throws IOException
      */
     public MessagePacker packByte(byte b)
             throws IOException
@@ -414,7 +414,7 @@ public MessagePacker packByte(byte b)
      *
      * @param v the integer to be written
      * @return this
-     * @throws IOException when underlaying output throws IOException
+     * @throws IOException when underlying output throws IOException
      */
     public MessagePacker packShort(short v)
             throws IOException
@@ -449,7 +449,7 @@ else if (v < (1 << 7)) {
      *
      * @param r the integer to be written
      * @return this
-     * @throws IOException when underlaying output throws IOException
+     * @throws IOException when underlying output throws IOException
      */
     public MessagePacker packInt(int r)
             throws IOException
@@ -491,7 +491,7 @@ else if (r < (1 << 16)) {
      *
      * @param v the integer to be written
      * @return this
-     * @throws IOException when underlaying output throws IOException
+     * @throws IOException when underlying output throws IOException
      */
     public MessagePacker packLong(long v)
             throws IOException
@@ -547,7 +547,7 @@ else if (v < (1 << 7)) {
      *
      * @param bi the integer to be written
      * @return this
-     * @throws IOException when underlaying output throws IOException
+     * @throws IOException when underlying output throws IOException
      */
     public MessagePacker packBigInteger(BigInteger bi)
             throws IOException
@@ -572,7 +572,7 @@ else if (bi.bitLength() == 64 && bi.signum() == 1) {
      *
      * @param v the value to be written
      * @return this
-     * @throws IOException when underlaying output throws IOException
+     * @throws IOException when underlying output throws IOException
      */
     public MessagePacker packFloat(float v)
             throws IOException
@@ -589,7 +589,7 @@ public MessagePacker packFloat(float v)
      *
      * @param v the value to be written
      * @return this
-     * @throws IOException when underlaying output throws IOException
+     * @throws IOException when underlying output throws IOException
      */
     public MessagePacker packDouble(double v)
             throws IOException
@@ -666,7 +666,7 @@ private int encodeStringToBufferAt(int pos, String s)
      *
      * @param s the string to be written
      * @return this
-     * @throws IOException when underlaying output throws IOException
+     * @throws IOException when underlying output throws IOException
      */
     public MessagePacker packString(String s)
             throws IOException
@@ -755,7 +755,7 @@ else if (s.length() < (1 << 16)) {
      *
      * @param arraySize number of elements to be written
      * @return this
-     * @throws IOException when underlaying output throws IOException
+     * @throws IOException when underlying output throws IOException
      */
     public MessagePacker packArrayHeader(int arraySize)
             throws IOException
@@ -786,7 +786,7 @@ else if (arraySize < (1 << 16)) {
      *
      * @param mapSize number of pairs to be written
      * @return this
-     * @throws IOException when underlaying output throws IOException
+     * @throws IOException when underlying output throws IOException
      */
     public MessagePacker packMapHeader(int mapSize)
             throws IOException
@@ -812,7 +812,7 @@ else if (mapSize < (1 << 16)) {
      *
      * @param v the value to be written
      * @return this
-     * @throws IOException when underlaying output throws IOException
+     * @throws IOException when underlying output throws IOException
      */
     public MessagePacker packValue(Value v)
             throws IOException
@@ -824,12 +824,12 @@ public MessagePacker packValue(Value v)
     /**
      * Writes header of an Extension value.
      * 
      
-     * You will call {@link #writePayload(byte[])} or {@link #addPayload(byte[])} method to write body binary.
+     * You MUST call {@link #writePayload(byte[])} or {@link #addPayload(byte[])} method to write body binary.
      *
      * @param extType the extension type tag to be written
      * @param payloadLen number of bytes of a payload binary to be written
      * @return this
-     * @throws IOException when underlaying output throws IOException
+     * @throws IOException when underlying output throws IOException
      */
     public MessagePacker packExtensionTypeHeader(byte extType, int payloadLen)
             throws IOException
@@ -877,11 +877,11 @@ else if (payloadLen < (1 << 16)) {
     /**
      * Writes header of a Binary value.
      * 
      
-     * You will call {@link #writePayload(byte[])} or {@link #addPayload(byte[])} method to write body binary.
+     * You MUST call {@link #writePayload(byte[])} or {@link #addPayload(byte[])} method to write body binary.
      *
      * @param len number of bytes of a binary to be written
      * @return this
-     * @throws IOException when underlaying output throws IOException
+     * @throws IOException when underlying output throws IOException
      */
     public MessagePacker packBinaryHeader(int len)
             throws IOException
@@ -903,12 +903,12 @@ else if (len < (1 << 16)) {
      * 
      
      * Length must be number of bytes of a string in UTF-8 encoding.
      * 
      
-     * You will call {@link #writePayload(byte[])} or {@link #addPayload(byte[])} method to write body of the
+     * You MUST call {@link #writePayload(byte[])} or {@link #addPayload(byte[])} method to write body of the
      * UTF-8 encoded string.
      *
      * @param len number of bytes of a UTF-8 string to be written
      * @return this
-     * @throws IOException when underlaying output throws IOException
+     * @throws IOException when underlying output throws IOException
      */
     public MessagePacker packRawStringHeader(int len)
             throws IOException
@@ -935,7 +935,7 @@ else if (len < (1 << 16)) {
      *
      * @param src the data to add
      * @return this
-     * @throws IOException when underlaying output throws IOException
+     * @throws IOException when underlying output throws IOException
      */
     public MessagePacker writePayload(byte[] src)
             throws IOException
@@ -952,7 +952,7 @@ public MessagePacker writePayload(byte[] src)
      * @param off the start offset in the data
      * @param len the number of bytes to add
      * @return this
-     * @throws IOException when underlaying output throws IOException
+     * @throws IOException when underlying output throws IOException
      */
     public MessagePacker writePayload(byte[] src, int off, int len)
             throws IOException
@@ -979,7 +979,7 @@ public MessagePacker writePayload(byte[] src, int off, int len)
      *
      * @param src the data to add
      * @return this
-     * @throws IOException when underlaying output throws IOException
+     * @throws IOException when underlying output throws IOException
      */
     public MessagePacker addPayload(byte[] src)
             throws IOException
@@ -999,7 +999,7 @@ public MessagePacker addPayload(byte[] src)
      * @param off the start offset in the data
      * @param len the number of bytes to add
      * @return this
-     * @throws IOException when underlaying output throws IOException
+     * @throws IOException when underlying output throws IOException
      */
     public MessagePacker addPayload(byte[] src, int off, int len)
             throws IOException
diff --git a/msgpack-core/src/main/java/org/msgpack/core/MessageUnpacker.java b/msgpack-core/src/main/java/org/msgpack/core/MessageUnpacker.java
index 99a42a5fb..82ed9d15f 100644
--- a/msgpack-core/src/main/java/org/msgpack/core/MessageUnpacker.java
+++ b/msgpack-core/src/main/java/org/msgpack/core/MessageUnpacker.java
@@ -93,14 +93,14 @@
  *             case ARRAY:
  *                 length = unpacker.unpackArrayHeader();
  *                 for (int i = 0; i < length; i++) {
- *                     readRecursively(unpack);
+ *                     readRecursively(unpacker);
  *                 }
  *                 break;
  *             case MAP:
  *                 length = unpacker.unpackMapHeader();
  *                 for (int i = 0; i < length; i++) {
- *                     readRecursively(unpack);  // key
- *                     readRecursively(unpack);  // value
+ *                     readRecursively(unpacker);  // key
+ *                     readRecursively(unpacker);  // value
  *                 }
  *                 break;
  *             case EXTENSION:
@@ -134,16 +134,16 @@
  * 
      Java typePacker methodMessagePack type
      
  *
  * 
      
- * To read a byte array, first you call {@link #unpackBinaryHeader} method to get length of the byte array. Then,
- * you call {@link #readPayload(int)} or {@link #readPayloadAsReference(int)} method to read the the contents.
+ * To read a byte array, first call {@link #unpackBinaryHeader} method to get length of the byte array. Then,
+ * call {@link #readPayload(int)} or {@link #readPayloadAsReference(int)} method to read the the contents.
  *
  * 
      
- * To read an Array type, first you call {@link #unpackArrayHeader()} method to get number of elements. Then,
- * you call unpacker methods for each element.
+ * To read an Array type, first call {@link #unpackArrayHeader()} method to get number of elements. Then,
+ * call unpacker methods for each element.
  *
  * 
      
- * To read a Map, first you call {@link #unpackMapHeader()} method to get number of pairs of the map. Then,
- * for each pair, you call unpacker methods for key first, and then value. You will call unpacker methods twice
+ * To read a Map, first call {@link #unpackMapHeader()} method to get number of pairs of the map. Then,
+ * for each pair, call unpacker methods for key first, and then value. will call unpacker methods twice
  * as many time as the returned count.
  *
  */
@@ -220,9 +220,9 @@ protected MessageUnpacker(MessageBufferInput in, MessagePack.UnpackerConfig conf
     }
 
     /**
-     * Replaces underlaying input.
+     * Replaces underlying input.
      * 
      
-     * This method clears internal buffer, swaps the underlaying input with the new given input, then returns
+     * This method clears internal buffer, swaps the underlying input with the new given input, then returns
      * the old input.
      *
      * 
      
@@ -252,7 +252,7 @@ public MessageBufferInput reset(MessageBufferInput in)
     /**
      * Returns total number of read bytes.
      * 
      
-     * This method returns total of amount of data consumed from the underlaying input minus size of data
+     * This method returns total of amount of data consumed from the underlying input minus size of data
      * remained still unused in the current internal buffer.
      *
      * 
      
@@ -383,7 +383,7 @@ private boolean ensureBuffer()
      * {@link #hasNext()} returns true.
      *
      * @return the next MessageFormat
-     * @throws IOException when underlaying input throws IOException
+     * @throws IOException when underlying input throws IOException
      * @throws MessageInsufficientBufferException when the end of file reached, i.e. {@link #hasNext()} == false.
      */
     public MessageFormat getNextFormat()
@@ -719,7 +719,7 @@ public Variable unpackValue(Variable var)
      * Reads a Nil byte.
      *
      * @throws MessageTypeException when value is not MessagePack Nil type
-     * @throws IOException when underlaying input throws IOException
+     * @throws IOException when underlying input throws IOException
      */
     public void unpackNil()
             throws IOException
@@ -736,7 +736,7 @@ public void unpackNil()
      *
      * @return the read value
      * @throws MessageTypeException when value is not MessagePack Boolean type
-     * @throws IOException when underlaying input throws IOException
+     * @throws IOException when underlying input throws IOException
      */
     public boolean unpackBoolean()
             throws IOException
@@ -759,7 +759,7 @@ else if (b == Code.TRUE) {
      * @return the read value
      * @throws MessageIntegerOverflowException when value doesn't fit in the range of byte
      * @throws MessageTypeException when value is not MessagePack Integer type
-     * @throws IOException when underlaying input throws IOException
+     * @throws IOException when underlying input throws IOException
      */
     public byte unpackByte()
             throws IOException
@@ -826,7 +826,7 @@ public byte unpackByte()
      * @return the read value
      * @throws MessageIntegerOverflowException when value doesn't fit in the range of short
      * @throws MessageTypeException when value is not MessagePack Integer type
-     * @throws IOException when underlaying input throws IOException
+     * @throws IOException when underlying input throws IOException
      */
     public short unpackShort()
             throws IOException
@@ -887,7 +887,7 @@ public short unpackShort()
      * @return the read value
      * @throws MessageIntegerOverflowException when value doesn't fit in the range of int
      * @throws MessageTypeException when value is not MessagePack Integer type
-     * @throws IOException when underlaying input throws IOException
+     * @throws IOException when underlying input throws IOException
      */
     public int unpackInt()
             throws IOException
@@ -942,7 +942,7 @@ public int unpackInt()
      * @return the read value
      * @throws MessageIntegerOverflowException when value doesn't fit in the range of long
      * @throws MessageTypeException when value is not MessagePack Integer type
-     * @throws IOException when underlaying input throws IOException
+     * @throws IOException when underlying input throws IOException
      */
     public long unpackLong()
             throws IOException
@@ -993,7 +993,7 @@ public long unpackLong()
      *
      * @return the read value
      * @throws MessageTypeException when value is not MessagePack Integer type
-     * @throws IOException when underlaying input throws IOException
+     * @throws IOException when underlying input throws IOException
      */
     public BigInteger unpackBigInteger()
             throws IOException
@@ -1049,7 +1049,7 @@ public BigInteger unpackBigInteger()
      *
      * @return the read value
      * @throws MessageTypeException when value is not MessagePack Float type
-     * @throws IOException when underlaying input throws IOException
+     * @throws IOException when underlying input throws IOException
      */
     public float unpackFloat()
             throws IOException
@@ -1071,7 +1071,7 @@ public float unpackFloat()
      *
      * @return the read value
      * @throws MessageTypeException when value is not MessagePack Float type
-     * @throws IOException when underlaying input throws IOException
+     * @throws IOException when underlying input throws IOException
      */
     public double unpackDouble()
             throws IOException
@@ -1242,7 +1242,7 @@ private String decodeStringFastPath(int length)
      * @return the size of the array to be read
      * @throws MessageTypeException when value is not MessagePack Array type
      * @throws MessageSizeException when size of the array is larger than 2^31 - 1
-     * @throws IOException when underlaying input throws IOException
+     * @throws IOException when underlying input throws IOException
      */
     public int unpackArrayHeader()
             throws IOException
@@ -1275,7 +1275,7 @@ public int unpackArrayHeader()
      * @return the size of the map to be read
      * @throws MessageTypeException when value is not MessagePack Map type
      * @throws MessageSizeException when size of the map is larger than 2^31 - 1
-     * @throws IOException when underlaying input throws IOException
+     * @throws IOException when underlying input throws IOException
      */
     public int unpackMapHeader()
             throws IOException
@@ -1416,7 +1416,7 @@ public int unpackRawStringHeader()
      * @return the size of the map to be read
      * @throws MessageTypeException when value is not MessagePack Map type
      * @throws MessageSizeException when size of the map is larger than 2^31 - 1
-     * @throws IOException when underlaying input throws IOException
+     * @throws IOException when underlying input throws IOException
      */
     public int unpackBinaryHeader()
             throws IOException
@@ -1471,7 +1471,7 @@ private void skipPayload(int numBytes)
      * until ByteBuffer.remaining() returns 0.
      *
      * @param dst the byte buffer into which the data is read
-     * @throws IOException when underlaying input throws IOException
+     * @throws IOException when underlying input throws IOException
      */
     public void readPayload(ByteBuffer dst)
             throws IOException
@@ -1500,7 +1500,7 @@ public void readPayload(ByteBuffer dst)
      * This method is equivalent to readPayload(dst, 0, dst.length).
      *
      * @param dst the byte array into which the data is read
-     * @throws IOException when underlaying input throws IOException
+     * @throws IOException when underlying input throws IOException
      */
     public void readPayload(byte[] dst)
             throws IOException
@@ -1518,7 +1518,7 @@ public void readPayload(byte[] dst)
      *
      * @param length number of bytes to be read
      * @return the new byte array
-     * @throws IOException when underlaying input throws IOException
+     * @throws IOException when underlying input throws IOException
      */
     public byte[] readPayload(int length)
             throws IOException
@@ -1536,7 +1536,7 @@ public byte[] readPayload(int length)
      * @param dst the byte array into which the data is read
      * @param off the offset in the dst array
      * @param len the number of bytes to read
-     * @throws IOException when underlaying input throws IOException
+     * @throws IOException when underlying input throws IOException
      */
     public void readPayload(byte[] dst, int off, int len)
             throws IOException
@@ -1554,7 +1554,7 @@ public void readPayload(byte[] dst, int off, int len)
      * allocated buffer if reference is not applicable.
      *
      * @param length number of bytes to be read
-     * @throws IOException when underlaying input throws IOException
+     * @throws IOException when underlying input throws IOException
      */
     public MessageBuffer readPayloadAsReference(int length)
             throws IOException
@@ -1595,7 +1595,7 @@ private int readNextLength32()
     }
 
     /**
-     * Closes underlaying input.
+     * Closes underlying input.
      *
      * @throws IOException
      */
diff --git a/msgpack-core/src/main/java/org/msgpack/core/buffer/ArrayBufferOutput.java b/msgpack-core/src/main/java/org/msgpack/core/buffer/ArrayBufferOutput.java
index df952a61a..cd31e6453 100644
--- a/msgpack-core/src/main/java/org/msgpack/core/buffer/ArrayBufferOutput.java
+++ b/msgpack-core/src/main/java/org/msgpack/core/buffer/ArrayBufferOutput.java
@@ -44,7 +44,7 @@ public ArrayBufferOutput(int bufferSize)
     }
 
     /**
-     * Gets size of the written data.
+     * Gets the size of the written data.
      *
      * @return number of bytes
      */
@@ -58,7 +58,7 @@ public int getSize()
     }
 
     /**
-     * Gets copy of the written data as a byte array.
+     * Gets a copy of the written data as a byte array.
      * 
      
      * If your application needs better performance and smaller memory consumption, you may prefer
      * {@link #toMessageBuffer()} or {@link #toBufferList()} to avoid copying.
diff --git a/msgpack-core/src/main/java/org/msgpack/core/buffer/MessageBuffer.java b/msgpack-core/src/main/java/org/msgpack/core/buffer/MessageBuffer.java
index 730cd245b..246e678a7 100644
--- a/msgpack-core/src/main/java/org/msgpack/core/buffer/MessageBuffer.java
+++ b/msgpack-core/src/main/java/org/msgpack/core/buffer/MessageBuffer.java
@@ -37,7 +37,7 @@
  * array-backed buffers.
  * 
      
  * MessageBuffer class itself is optimized for little-endian CPU archtectures so that JVM (HotSpot) can take advantage
- * of the fastest JIT format which skips TypeProfile checking. To ensure this performance, applications must not load
+ * of the fastest JIT format which skips TypeProfile checking. To ensure this performance, applications must not import
  * unnecessary classes such as MessagePackBE. On big-endian CPU archtectures, it automatically uses a subclass that
  * includes TypeProfile overhead but still faster than stndard ByteBuffer class. On JVMs older than Java 7 and JVMs
  * without Unsafe API (such as Android), implementation falls back to an universal implementation that uses ByteBuffer
@@ -213,7 +213,7 @@ public static MessageBuffer allocate(int size)
      * The new buffer's size will be array.length. hasArray() will return true.
      *
      * @param array the byte array that will gack this MessageBuffer
-     * @return the new MessageBuffer
+     * @return a new MessageBuffer that wraps the given byte array
      *
      */
     public static MessageBuffer wrap(byte[] array)
@@ -231,7 +231,7 @@ public static MessageBuffer wrap(byte[] array)
      * @param array the byte array that will gack this MessageBuffer
      * @param offset The offset of the subarray to be used; must be non-negative and no larger than array.length
      * @param length The length of the subarray to be used; must be non-negative and no larger than array.length - offset
-     * @return the new MessageBuffer
+     * @return a new MessageBuffer that wraps the given byte array
      *
      */
     public static MessageBuffer wrap(byte[] array, int offset, int length)
@@ -249,7 +249,7 @@ public static MessageBuffer wrap(byte[] array, int offset, int length)
      * @param bb the byte buffer that will gack this MessageBuffer
      * @throws IllegalArgumentException given byte buffer returns false both from hasArray() and isDirect()
      * @throws UnsupportedOperationException given byte buffer is a direct buffer and this platform doesn't support Unsafe API
-     * @return the new MessageBuffer
+     * @return a new MessageBuffer that wraps the given byte array
      *
      */
     public static MessageBuffer wrap(ByteBuffer bb)
@@ -304,7 +304,7 @@ private static MessageBuffer newInstance(Constructor constructor, Object... a
         }
         catch (InvocationTargetException e) {
             if (e.getCause() instanceof RuntimeException) {
-                // underlaying constructor may throw RuntimeException
+                // underlying constructor may throw RuntimeException
                 throw (RuntimeException) e.getCause();
             }
             else if (e.getCause() instanceof Error) {
@@ -381,7 +381,7 @@ protected MessageBuffer(Object base, long address, int length)
     }
 
     /**
-     * Gets size of the buffer.
+     * Gets the size of the buffer.
      *
      * MessageBuffer doesn't have limit unlike ByteBuffer. Instead, you can use {@link #slice(int, int)} to get a
      * part of the buffer.