docs: fixes warnings

Author: frsyuki

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

@@ -447,7 +447,7 @@ else if (v < (1 << 7)) {
      * <p>
      * 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) {
      * <p>
      * 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)
      * <p>
      * 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)
      * <p>
      * 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.
      * <p>
-     * 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.
      * <p>
-     * 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

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

@@ -47,7 +47,7 @@
  * <p>
  * 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.
  * <p>
  * 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.
  *
  * <p>
- * 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
      * <p>
      * 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
      */

msgpack-core/src/main/java/org/msgpack/core/buffer/MessageBuffer.java

@@ -33,7 +33,7 @@
  * big-endian order.
  * <p>
  * 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.
  * <p>
  * 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()
     {

msgpack-core/src/main/java/org/msgpack/core/buffer/MessageBufferInput.java

@@ -43,7 +43,7 @@ MessageBuffer next()
     /**
      * Closes the input.
      * <p>
-     * 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.
      * <p>
      * If the input is already closed then invoking this method has no effect.

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.
      * <p>
      * 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.
      * <p>
-     * 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.
      * <p>
-     * 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)

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

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

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

msgpack-core/src/main/java/org/msgpack/value/ValueType.java

@@ -18,8 +18,8 @@
 /**
  * Representation of MessagePack types.
  * <p>
- * 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