Code Review Request, JDK-8184316, Typo in javax.net.ssl.SSLServerSocket class documentation

Xuelei Fan xuelei.fan at oracle.com
Tue Jul 25 16:32:38 UTC 2017


I missed a comment.

javax/net/ssl/SSLServerSocket.java
----------------------------------
  /**
- * This class extends <code>ServerSocket</code>s and
+ * This class extends <code>ServerSocket</code> and
   * provides secure server sockets using protocols such as the Secure
   * Sockets Layer (SSL) or Transport Layer Security (TLS) protocols.
   * <P>
- * Instances of this class are generally created using a
+ * Instances of this class are generally created using an
   * <code>SSLServerSocketFactory</code>.  The primary function
- * of <code>SSLServerSocket</code>s
+ * of an <code>SSLServerSocket</code>
   * is to create <code>SSLSocket</code>s by <code>accept</code>ing
   * connections.
   * <P>
- * <code>SSLServerSocket</code>s contain several pieces of state data
+ * An <code>SSLServerSocket</code> contains several pieces of state data
   * which are inherited by the <code>SSLSocket</code> at
   * socket creation.  These include the enabled cipher
   * suites and protocols, whether client


javax/net/ssl/SSLSocket.java
----------------------------
  /**
- * This class extends <code>Socket</code>s and provides secure
- * socket using protocols such as the "Secure
+ * This class extends <code>Socket</code> and provides secure
+ * sockets using protocols such as the "Secure
   * Sockets Layer" (SSL) or IETF "Transport Layer Security" (TLS) 
protocols.
   * <P>
   * Such sockets are normal stream sockets, but they
@@ -105,7 +105,7 @@
   * non-private (unencrypted) communications will such a ciphersuite be
   * selected.
   *
- * <P>When <code>SSLSocket</code>s are first created, no handshaking
+ * <P>When an <code>SSLSocket</code> is first created, no handshaking
   * is done so that applications may first set their communication
   * preferences:  what cipher suites to use, whether the socket should be
   * in client or server mode, etc.
@@ -118,7 +118,7 @@
   * objects are passed to <em>HandshakeCompletedListener</em> instances,
   * which are registered by users of this API.
   *
- * <code>SSLSocket</code>s are created by <code>SSLSocketFactory</code>s,
+ * An <code>SSLSocket</code> is created by <code>SSLSocketFactory</code>,
   * or by <code>accept</code>ing a connection from a
   * <code>SSLServerSocket</code>.
   *

Thanks,
Xuelei
On 7/25/2017 9:26 AM, Xuelei Fan wrote:
> Good catch!  More update:
> 
> javax/net/ssl/SSLServerSocket.java
> ----------------------------------
>   /**
> - * This class extends <code>ServerSocket</code>s and
> + * This class extends <code>ServerSocket</code> and
>    * provides secure server sockets using protocols such as the Secure
>    * Sockets Layer (SSL) or Transport Layer Security (TLS) protocols.
>    * <P>
>    * Instances of this class are generally created using a
>    * <code>SSLServerSocketFactory</code>.  The primary function
> - * of <code>SSLServerSocket</code>s
> + * of <code>SSLServerSocket</code>
>    * is to create <code>SSLSocket</code>s by <code>accept</code>ing
>    * connections.
>    * <P>
> - * <code>SSLServerSocket</code>s contain several pieces of state data
> + * <code>SSLServerSocket</code> contains several pieces of state data
>    * which are inherited by the <code>SSLSocket</code> at
>    * socket creation.  These include the enabled cipher
>    * suites and protocols, whether client
> 
> 
> javax/net/ssl/SSLSocket.java
> ----------------------------
>   /**
> - * This class extends <code>Socket</code>s and provides secure
> - * socket using protocols such as the "Secure
> + * This class extends <code>Socket</code> and provides secure
> + * sockets using protocols such as the "Secure
>    * Sockets Layer" (SSL) or IETF "Transport Layer Security" (TLS) 
> protocols.
>    * <P>
>    * Such sockets are normal stream sockets, but they
> @@ -105,7 +105,7 @@
>    * non-private (unencrypted) communications will such a ciphersuite be
>    * selected.
>    *
> - * <P>When <code>SSLSocket</code>s are first created, no handshaking
> + * <P>When <code>SSLSocket</code> is first created, no handshaking
>    * is done so that applications may first set their communication
>    * preferences:  what cipher suites to use, whether the socket should be
>    * in client or server mode, etc.
> @@ -118,7 +118,7 @@
>    * objects are passed to <em>HandshakeCompletedListener</em> instances,
>    * which are registered by users of this API.
>    *
> - * <code>SSLSocket</code>s are created by <code>SSLSocketFactory</code>s,
> + * <code>SSLSocket</code> is created by <code>SSLSocketFactory</code>,
>    * or by <code>accept</code>ing a connection from a
>    * <code>SSLServerSocket</code>.
> 
> 
> Thanks,
> Xuelei
> 
> On 7/25/2017 9:14 AM, Sean Mullan wrote:
>> SSLSocket has the same typo in its first sentence ("extends Sockets"), 
>> and should also say "provides secure sockets" (note the plural 
>> sockets). Can you fix that as part of this too?
>>
>> One wording improvement below:
>>
>> On 7/25/17 12:02 PM, Xuelei Fan wrote:
>>> Hi,
>>>
>>> Please review the document typo update for:
>>>     https://bugs.openjdk.java.net/browse/JDK-8184316
>>>
>>> The diff on javax/net/ssl/SSLServerSocket.java looks like:
>>>
>>>   /**
>>> - * This class extends <code>ServerSocket</code>s and
>>> + * This class extends <code>ServerSocket</code> and
>>>    * provides secure server sockets using protocols such as the Secure
>>>    * Sockets Layer (SSL) or Transport Layer Security (TLS) protocols.
>>>    * <P>
>>> @@ -41,7 +41,7 @@
>>>    * is to create <code>SSLSocket</code>s by <code>accept</code>ing
>>>    * connections.
>>>    * <P>
>>> - * <code>SSLServerSocket</code>s contain several pieces of state data
>>> + * <code>SSLServerSocket</code> contains several pieces of state data
>>
>> An SSLServerSocket contains ...
>>
>>>    * which are inherited by the <code>SSLSocket</code> at
>>>    * socket creation.  These include the enabled cipher
>>>    * suites and protocols, whether client
>>>
>>> Thanks,
>>> Xuelei


More information about the security-dev mailing list