ServerSocket: javadoc can be improved
1.
@param:
The description begins with a lowercase letter if it is a phrase (contains no verb),
or an uppercase letter if it is a sentence. End the phrase with a period only if
another phrase or sentence follows it.
* When writing a phrase, do not capitalize and do not end with a period:
@param x the x-coordinate, measured in pixels
* When writing a phrase followed by a sentence, do not capitalize the phrase,
but end it with a period to distinguish it from the start of the next sentence:
@param x the x-coordinate. Measured in pixels.
* If you prefer starting with a sentence, capitalize it and end it with a period:
@param x Specifies the x-coordinate, measured in pixels.
* When writing multiple sentences, follow normal sentence rules:
@param x Specifies the x-coordinate. Measured in pixels.
Should start with a lowercase letter and be without period at the end:
* port - the port number, or 0 to use a port number that is automatically allocated.
* backlog - the maximum length of the queue.
* endpoint - The IP address & port number to bind to.
* backlog - The listen backlog length.
* fac - the desired factory.
In my opinion it would be better to use either "the maximum length of the queue" or
"the listen backlog length" everywhere for backlog description. In general the
specification should use the same words/phrases for the same things.
It helps avoid confusions and makes specification easier for understanding.
Should end with a period:
* connectionTime - An int expressing the relative importance of a short
connection time
* latency - An int expressing the relative importance of low latency
* bandwidth - An int expressing the relative importance of high bandwidth
or (may be better) should be a phrase:
connectionTime - relative importance of a short connection time
latency - relative importance of low latency
bandwidth - relative importance of high bandwidth
2.@return (reference page)
Use the same capitalization and punctuation as you used in @param.
Should be without period at the end:
* the value of the SO_RCVBUF option for this Socket.
Should start with uppercase:
* the address to which this socket is bound, or null if the socket is unbound.
* the port number to which this socket is listening or -1 if the socket is not
bound yet.
* a SocketAddress representing the local endpoint of this socket, or null if
it is not bound yet.
* a boolean indicating whether or not SO_REUSEADDR is enabled.
3.
"The port must be between 0 and 65535, inclusive" can be removed from the
3-arg constructor description. It is well-know restriction, and it is OK
just to have it mentioned in the "Throws" section.
4.
Inconsistence in sentences:
-Creates a server socket, bound to the specified port.
-Creates a server socket and binds it to the specified local port number.
-Create a server with the specified port, listen backlog, and local IP
address to bind to.
Sometimes "socket", sometimes "server socket", sometimes "port", and sometimes
"local port" is used. It would be better to use the same words/phrases for the
same things. It helps avoid confusions and makes specification more clear and
easier for understanding. If any difference between "port" and "local port"
is really exist may be we should mention this explicitly.
5.
we should use 3-rd person:
* Create a server with the specified port, listen backlog, and local IP
address to bind to.
Need to replace "Create" with "Creates"
6.
More descriptive Javadoc can be written:
* s - the Socket
1.
@param:
The description begins with a lowercase letter if it is a phrase (contains no verb),
or an uppercase letter if it is a sentence. End the phrase with a period only if
another phrase or sentence follows it.
* When writing a phrase, do not capitalize and do not end with a period:
@param x the x-coordinate, measured in pixels
* When writing a phrase followed by a sentence, do not capitalize the phrase,
but end it with a period to distinguish it from the start of the next sentence:
@param x the x-coordinate. Measured in pixels.
* If you prefer starting with a sentence, capitalize it and end it with a period:
@param x Specifies the x-coordinate, measured in pixels.
* When writing multiple sentences, follow normal sentence rules:
@param x Specifies the x-coordinate. Measured in pixels.
Should start with a lowercase letter and be without period at the end:
* port - the port number, or 0 to use a port number that is automatically allocated.
* backlog - the maximum length of the queue.
* endpoint - The IP address & port number to bind to.
* backlog - The listen backlog length.
* fac - the desired factory.
In my opinion it would be better to use either "the maximum length of the queue" or
"the listen backlog length" everywhere for backlog description. In general the
specification should use the same words/phrases for the same things.
It helps avoid confusions and makes specification easier for understanding.
Should end with a period:
* connectionTime - An int expressing the relative importance of a short
connection time
* latency - An int expressing the relative importance of low latency
* bandwidth - An int expressing the relative importance of high bandwidth
or (may be better) should be a phrase:
connectionTime - relative importance of a short connection time
latency - relative importance of low latency
bandwidth - relative importance of high bandwidth
2.@return (reference page)
Use the same capitalization and punctuation as you used in @param.
Should be without period at the end:
* the value of the SO_RCVBUF option for this Socket.
Should start with uppercase:
* the address to which this socket is bound, or null if the socket is unbound.
* the port number to which this socket is listening or -1 if the socket is not
bound yet.
* a SocketAddress representing the local endpoint of this socket, or null if
it is not bound yet.
* a boolean indicating whether or not SO_REUSEADDR is enabled.
3.
"The port must be between 0 and 65535, inclusive" can be removed from the
3-arg constructor description. It is well-know restriction, and it is OK
just to have it mentioned in the "Throws" section.
4.
Inconsistence in sentences:
-Creates a server socket, bound to the specified port.
-Creates a server socket and binds it to the specified local port number.
-Create a server with the specified port, listen backlog, and local IP
address to bind to.
Sometimes "socket", sometimes "server socket", sometimes "port", and sometimes
"local port" is used. It would be better to use the same words/phrases for the
same things. It helps avoid confusions and makes specification more clear and
easier for understanding. If any difference between "port" and "local port"
is really exist may be we should mention this explicitly.
5.
we should use 3-rd person:
* Create a server with the specified port, listen backlog, and local IP
address to bind to.
Need to replace "Create" with "Creates"
6.
More descriptive Javadoc can be written:
* s - the Socket