Summary

The method description of SSLEngine.unwrap(ByteBuffer src, ByteBuffer [] dsts, int offset, int length) could be more clear that 'inbound network buffer' is the 'src' ByteBuffer

Problem

During the fix for JDK-8283577, I thought the spec did not say that the src ByteBuffer may be overwritten. During review, I found it was already documented; however, the buffer is referred to as the 'inbound network buffer' not 'src'. The parameter definition for 'src' entry does say it is the "inbound network buffer", but when much of the text refers to 'src', using other terminology can be missed or confusing.

Solution

The simplest fix is to just add 'src' to the paragraph so there is no confusion.

Specification

src/java.base/share/classes/javax/net/ssl/SSLEngine.java

  * <P>
- * The inbound network buffer may be modified as a result of this
- * call:  therefore if the network data packet is required for some
+ * The inbound network buffer, {@code src}, may be modified as a result of
+ * this call:  therefore if the network data packet is required for some
  * secondary purpose, the data should be duplicated before calling this
  * method.  Note:  the network data will not be useful to a second
  * SSLEngine, as each SSLEngine contains unique random state which
  * influences the SSL/TLS/DTLS messages.
  * <P>