MessagePacker: Improve and clarify use in documentation for addPayload()

atnak · atnak · commit c2133553c3be · 2018-04-16T11:03:47.000+09:00
diff --git a/msgpack-core/src/main/java/org/msgpack/core/MessagePacker.java b/msgpack-core/src/main/java/org/msgpack/core/MessagePacker.java
@@ -1025,13 +1025,17 @@ public MessagePacker writePayload(byte[] src, int off, int len)
     /**
      * Writes a byte array to the output.
      * <p>
-     * 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.
+     * This method is used with {@link #packRawStringHeader(int)} or {@link #packBinaryHeader(int)} methods.
+     * <p>
+     * Unlike {@link #writePayload(byte[])} method, this method does not make a defensive copy of the given byte
+     * array, even if it 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
      * @throws IOException when underlying output throws IOException
+     * @see #writePayload(byte[])
      */
     public MessagePacker addPayload(byte[] src)
             throws IOException
@@ -1042,16 +1046,19 @@ public MessagePacker addPayload(byte[] src)
     /**
      * Writes a byte array to the output.
      * <p>
-     * 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.
+     * This method is used with {@link #packRawStringHeader(int)} or {@link #packBinaryHeader(int)} methods.
+     * <p>
+     * Unlike {@link #writePayload(byte[], int, int)} method, this method does not make a defensive copy of the
+     * given byte array, even if it 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
      * @param off the start offset in the data
      * @param len the number of bytes to add
      * @return this
      * @throws IOException when underlying output throws IOException
+     * @see #writePayload(byte[], int, int)
      */
     public MessagePacker addPayload(byte[] src, int off, int len)
             throws IOException
