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

classic Classic list List threaded Threaded
6 messages Options
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

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

Xuelei Fan-2
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
   * which are inherited by the <code>SSLSocket</code> at
   * socket creation.  These include the enabled cipher
   * suites and protocols, whether client

Thanks,
Xuelei
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

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

Sean Mullan
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
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

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

Xuelei Fan-2
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
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

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

Xuelei Fan-2
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
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

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

Sean Mullan
In reply to this post by Xuelei Fan-2
On 7/25/17 12:26 PM, 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

I think this sentence sounds better if it starts with "An
SSLServerSocket ...". Same comment below ...

>    * 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>,

"An SSLSocket ..."

--Sean
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

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

Sean Mullan
In reply to this post by Xuelei Fan-2
Looks good now.

--Sean

On 7/25/17 12:32 PM, Xuelei Fan wrote:

> 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
Loading...