Documentation improvements for socket options.

Bug: http://code.google.com/p/android/issues/detail?id=13898
Change-Id: I202a5404e7e828f074483a3f6365b4e3a941da7d

8 files changed, 98 insertions, 237 deletions

diff --git a/luni/src/main/java/java/net/DatagramSocket.java b/luni/src/main/java/java/net/DatagramSocket.java
index a3900ba..5237e49 100644
--- a/luni/src/main/java/java/net/DatagramSocket.java
+++ b/luni/src/main/java/java/net/DatagramSocket.java
@@ -268,11 +268,7 @@ public class DatagramSocket {
     }
 
     /**
-     * Gets the socket receive buffer size. ( {@code SocketOptions.SO_RCVBUF} )
-     *
-     * @return the input buffer size.
-     * @throws SocketException
-     *                if an error occurs while getting the option value.
+     * Returns this socket's {@link SocketOptions#SO_RCVBUF receive buffer size}.
      */
     public synchronized int getReceiveBufferSize() throws SocketException {
         checkClosedAndBind(false);
@@ -280,11 +276,7 @@ public class DatagramSocket {
     }
 
     /**
-     * Gets the socket send buffer size. ( {@code SocketOptions.SO_SNDBUF} )
-     *
-     * @return the output buffer size.
-     * @throws SocketException
-     *                if an error occurs while getting the option value.
+     * Returns this socket's {@link SocketOptions#SO_SNDBUF send buffer size}.
      */
     public synchronized int getSendBufferSize() throws SocketException {
         checkClosedAndBind(false);
@@ -462,15 +454,7 @@ public class DatagramSocket {
     }
 
     /**
-     * Sets the socket send buffer size. This buffer size determines which the
-     * maximum packet size is that can be sent over this socket. It depends on
-     * the network implementation what will happen if the packet is bigger than
-     * the buffer size. ( {@code SocketOptions.SO_SNDBUF} )
-     *
-     * @param size
-     *            the buffer size in bytes. The size must be at least one byte.
-     * @throws SocketException
-     *                if an error occurs while setting the option.
+     * Sets this socket's {@link SocketOptions#SO_SNDBUF send buffer size}.
      */
     public synchronized void setSendBufferSize(int size) throws SocketException {
         if (size < 1) {
@@ -481,15 +465,7 @@ public class DatagramSocket {
     }
 
     /**
-     * Sets the socket receive buffer size. This buffer size determines which
-     * the maximum packet size is that can be received over this socket. It
-     * depends on the network implementation what will happen if the packet is
-     * bigger than the buffer size. ( {@code SocketOptions.SO_RCVBUF} )
-     *
-     * @param size
-     *            the buffer size in bytes. The size must be at least one byte.
-     * @throws SocketException
-     *                if an error occurs while setting the option.
+     * Sets this socket's {@link SocketOptions#SO_SNDBUF receive buffer size}.
      */
     public synchronized void setReceiveBufferSize(int size) throws SocketException {
         if (size < 1) {
diff --git a/luni/src/main/java/java/net/InetAddress.java b/luni/src/main/java/java/net/InetAddress.java
index bc414c7..e4ca164 100644
--- a/luni/src/main/java/java/net/InetAddress.java
+++ b/luni/src/main/java/java/net/InetAddress.java
@@ -910,7 +910,7 @@ public class InetAddress implements Serializable {
      * @param ipAddress
      *            either a 4 (IPv4) or 16 (IPv6) byte array.
      * @param scope_id
-     *            the scope id for an IPV6 scoped address. If not a scoped
+     *            the scope id for an IPv6 scoped address. If not a scoped
      *            address just pass in 0.
      * @return the InetAddress
      * @throws UnknownHostException
diff --git a/luni/src/main/java/java/net/MulticastSocket.java b/luni/src/main/java/java/net/MulticastSocket.java
index 4f6f2f4..c853dc4 100644
--- a/luni/src/main/java/java/net/MulticastSocket.java
+++ b/luni/src/main/java/java/net/MulticastSocket.java
@@ -28,6 +28,9 @@ import org.apache.harmony.luni.net.PlainDatagramSocketImpl;
  * @see DatagramSocket
  */
 public class MulticastSocket extends DatagramSocket {
+    private static final int NO_INTERFACE_INDEX = 0;
+    private static final int UNSET_INTERFACE_INDEX = -1;
+
     private InetAddress interfaceSet;
 
     /**
@@ -71,7 +74,7 @@ public class MulticastSocket extends DatagramSocket {
             InetAddress ipvXaddress = (InetAddress) impl
                     .getOption(SocketOptions.IP_MULTICAST_IF);
             if (ipvXaddress.isAnyLocalAddress()) {
-                // the address was not set at the IPV4 level so check the IPV6
+                // the address was not set at the IPv4 level so check the IPv6
                 // level
                 NetworkInterface theInterface = getNetworkInterface();
                 if (theInterface != null) {
@@ -105,13 +108,13 @@ public class MulticastSocket extends DatagramSocket {
     public NetworkInterface getNetworkInterface() throws SocketException {
         checkClosedAndBind(false);
 
-        // check if it is set at the IPV6 level. If so then use that. Otherwise
-        // do it at the IPV4 level
+        // check if it is set at the IPv6 level. If so then use that. Otherwise
+        // do it at the IPv4 level
         Integer theIndex = Integer.valueOf(0);
         try {
             theIndex = (Integer) impl.getOption(SocketOptions.IP_MULTICAST_IF2);
         } catch (SocketException e) {
-            // we may get an exception if IPV6 is not enabled.
+            // we may get an exception if IPv6 is not enabled.
         }
 
         if (theIndex.intValue() != 0) {
@@ -124,7 +127,7 @@ public class MulticastSocket extends DatagramSocket {
             }
         }
 
-        // ok it was not set at the IPV6 level so try at the IPV4 level
+        // ok it was not set at the IPv6 level so try at the IPv4 level
         InetAddress theAddress = (InetAddress) impl.getOption(SocketOptions.IP_MULTICAST_IF);
         if (theAddress != null) {
             if (!theAddress.isAnyLocalAddress()) {
@@ -140,8 +143,7 @@ public class MulticastSocket extends DatagramSocket {
             } else {
                 theAddresses[0] = Inet4Address.ANY;
             }
-            return new NetworkInterface(null, null, theAddresses,
-                    NetworkInterface.UNSET_INTERFACE_INDEX);
+            return new NetworkInterface(null, null, theAddresses, UNSET_INTERFACE_INDEX);
         }
 
         // ok not set at all so return null
@@ -355,9 +357,9 @@ public class MulticastSocket extends DatagramSocket {
         }
 
         /*
-         * now we should also make sure this works for IPV6 get the network
+         * now we should also make sure this works for IPv6 get the network
          * interface for the address and set the interface using its index
-         * however if IPV6 is not enabled then we may get an exception. if IPV6
+         * however if IPv6 is not enabled then we may get an exception. if IPv6
          * is not enabled
          */
         NetworkInterface theInterface = NetworkInterface.getByInetAddress(addr);
@@ -404,26 +406,25 @@ public class MulticastSocket extends DatagramSocket {
             throw new SocketException("No address associated with interface: " + netInterface);
         }
 
-        if (netInterface.getIndex() == NetworkInterface.UNSET_INTERFACE_INDEX) {
+        if (netInterface.getIndex() == UNSET_INTERFACE_INDEX) {
             // set the address using IP_MULTICAST_IF to make sure this
-            // works for both IPV4 and IPV6
+            // works for both IPv4 and IPv6
             impl.setOption(SocketOptions.IP_MULTICAST_IF, Inet4Address.ANY);
 
             try {
                 // we have the index so now we pass set the interface
                 // using IP_MULTICAST_IF2. This is what is used to set
-                // the interface on systems which support IPV6
-                impl.setOption(SocketOptions.IP_MULTICAST_IF2, Integer
-                        .valueOf(NetworkInterface.NO_INTERFACE_INDEX));
+                // the interface on systems which support IPv6
+                impl.setOption(SocketOptions.IP_MULTICAST_IF2, Integer.valueOf(NO_INTERFACE_INDEX));
             } catch (SocketException e) {
                 // for now just do this, -- could be narrowed?
             }
         }
 
         /*
-         * Now try to set using IPV4 way. However, if interface passed in has no
+         * Now try to set using IPv4 way. However, if interface passed in has no
          * IP addresses associated with it then we cannot do it. first we have
-         * to make sure there is an IPV4 address that we can use to call set
+         * to make sure there is an IPv4 address that we can use to call set
          * interface otherwise we will not set it
          */
         Enumeration<InetAddress> theAddresses = netInterface.getInetAddresses();
@@ -436,8 +437,8 @@ public class MulticastSocket extends DatagramSocket {
                 found = true;
             }
         }
-        if (netInterface.getIndex() == NetworkInterface.NO_INTERFACE_INDEX) {
-            // the system does not support IPV6 and does not provide
+        if (netInterface.getIndex() == NO_INTERFACE_INDEX) {
+            // the system does not support IPv6 and does not provide
             // indexes for the network interfaces. Just pass in the
             // first address for the network interface
             if (firstAddress != null) {
@@ -445,14 +446,14 @@ public class MulticastSocket extends DatagramSocket {
             } else {
                 /*
                  * we should never get here as there should not be any network
-                 * interfaces which have no IPV4 address and which does not have
+                 * interfaces which have no IPv4 address and which does not have
                  * the network interface index not set correctly
                  */
                 throw new SocketException("No address associated with interface: " + netInterface);
             }
         } else {
             // set the address using IP_MULTICAST_IF to make sure this
-            // works for both IPV4 and IPV6
+            // works for both IPv4 and IPv6
             if (firstAddress != null) {
                 impl.setOption(SocketOptions.IP_MULTICAST_IF, firstAddress);
             }
@@ -460,7 +461,7 @@ public class MulticastSocket extends DatagramSocket {
             try {
                 // we have the index so now we pass set the interface
                 // using IP_MULTICAST_IF2. This is what is used to set
-                // the interface on systems which support IPV6
+                // the interface on systems which support IPv6
                 impl.setOption(SocketOptions.IP_MULTICAST_IF2, Integer
                         .valueOf(netInterface.getIndex()));
             } catch (SocketException e) {
diff --git a/luni/src/main/java/java/net/NetworkInterface.java b/luni/src/main/java/java/net/NetworkInterface.java
index c5675b3..d86cca2 100644
--- a/luni/src/main/java/java/net/NetworkInterface.java
+++ b/luni/src/main/java/java/net/NetworkInterface.java
@@ -36,24 +36,17 @@ public final class NetworkInterface extends Object {
 
     private static final int CHECK_CONNECT_NO_PORT = -1;
 
-    static final int NO_INTERFACE_INDEX = 0;
-    static final int UNSET_INTERFACE_INDEX = -1;
-
     private final String name;
     private final String displayName;
     private final List<InterfaceAddress> interfaceAddresses = new LinkedList<InterfaceAddress>();
 
+    private final int interfaceIndex;
     private final List<InetAddress> addresses = new LinkedList<InetAddress>();
 
-    // The interface index is a positive integer which is non-negative. Where
-    // value is zero then we do not have an index for the interface (which
-    // occurs in systems which only support IPV4)
-    private int interfaceIndex;
+    private final List<NetworkInterface> children = new LinkedList<NetworkInterface>();
 
     private NetworkInterface parent = null;
 
-    private final List<NetworkInterface> children = new LinkedList<NetworkInterface>();
-
     private static NetworkInterface[] getNetworkInterfacesImpl() throws SocketException {
         Map<String, NetworkInterface> networkInterfaces = new LinkedHashMap<String, NetworkInterface>();
         for (InterfaceAddress ia : getAllInterfaceAddressesImpl()) {
@@ -86,7 +79,7 @@ public final class NetworkInterface extends Object {
      *            the Internet addresses associated with the interface.
      * @param interfaceIndex
      *            an index for the interface. Only set for platforms that
-     *            support IPV6.
+     *            support IPv6.
      */
     NetworkInterface(String name, String displayName, InetAddress[] addresses,
             int interfaceIndex) {
@@ -102,7 +95,7 @@ public final class NetworkInterface extends Object {
 
     /**
      * Returns the index for the network interface. Unless the system supports
-     * IPV6 this will be 0.
+     * IPv6 this will be 0.
      *
      * @return the index
      */
diff --git a/luni/src/main/java/java/net/ServerSocket.java b/luni/src/main/java/java/net/ServerSocket.java
index 24aab75..edce448 100644
--- a/luni/src/main/java/java/net/ServerSocket.java
+++ b/luni/src/main/java/java/net/ServerSocket.java
@@ -487,14 +487,7 @@ public class ServerSocket {
     }
 
     /**
-     * Sets the server socket receive buffer size {@code
-     * SocketOptions.SO_RCVBUF}.
-     *
-     * @param size
-     *            the buffer size in bytes.
-     * @throws SocketException
-     *             if an error occurs while setting the size or the size is
-     *             invalid.
+     * Sets this socket's {@link SocketOptions#SO_SNDBUF receive buffer size}.
      */
     public void setReceiveBufferSize(int size) throws SocketException {
         checkClosedAndCreate(true);
@@ -505,12 +498,7 @@ public class ServerSocket {
     }
 
     /**
-     * Gets the value for the receive buffer size socket option {@code
-     * SocketOptions.SO_RCVBUF}.
-     *
-     * @return the receive buffer size of this socket.
-     * @throws SocketException
-     *             if an error occurs while reading the option value.
+     * Returns this socket's {@link SocketOptions#SO_RCVBUF receive buffer size}.
      */
     public int getReceiveBufferSize() throws SocketException {
         checkClosedAndCreate(true);
diff --git a/luni/src/main/java/java/net/Socket.java b/luni/src/main/java/java/net/Socket.java
index bf79f4a..39abdbe 100644
--- a/luni/src/main/java/java/net/Socket.java
+++ b/luni/src/main/java/java/net/Socket.java
@@ -372,10 +372,8 @@ public class Socket {
     }
 
     /**
-     * Gets the IP address of the target host this socket is connected to.
-     *
-     * @return the IP address of the connected target host or {@code null} if
-     *         this socket is not yet connected.
+     * Returns the IP address of the target host this socket is connected to, or null if this
+     * socket is not yet connected.
      */
     public InetAddress getInetAddress() {
         if (!isConnected()) {
@@ -385,7 +383,7 @@ public class Socket {
     }
 
     /**
-     * Gets an input stream to read data from this socket.
+     * Returns an input stream to read data from this socket.
      *
      * @return the byte-oriented input stream.
      * @throws IOException
@@ -401,13 +399,7 @@ public class Socket {
     }
 
     /**
-     * Gets the setting of the socket option {@code SocketOptions.SO_KEEPALIVE}.
-     *
-     * @return {@code true} if the {@code SocketOptions.SO_KEEPALIVE} is
-     *         enabled, {@code false} otherwise.
-     * @throws SocketException
-     *             if an error occurs while reading the socket option.
-     * @see SocketOptions#SO_KEEPALIVE
+     * Returns this socket's {@link SocketOptions#SO_KEEPALIVE} setting.
      */
     public boolean getKeepAlive() throws SocketException {
         checkOpenAndCreate(true);
@@ -433,7 +425,7 @@ public class Socket {
     }
 
     /**
-     * Gets an output stream to write data into this socket.
+     * Returns an output stream to write data into this socket.
      *
      * @return the byte-oriented output stream.
      * @throws IOException
@@ -449,10 +441,8 @@ public class Socket {
     }
 
     /**
-     * Gets the port number of the target host this socket is connected to.
-     *
-     * @return the port number of the connected target host or {@code 0} if this
-     *         socket is not yet connected.
+     * Returns the port number of the target host this socket is connected to, or 0 if this socket
+     * is not yet connected.
      */
     public int getPort() {
         if (!isConnected()) {
@@ -462,13 +452,8 @@ public class Socket {
     }
 
     /**
-     * Gets the value of the socket option {@link SocketOptions#SO_LINGER}.
-     *
-     * @return the current value of the option {@code SocketOptions.SO_LINGER}
-     *         or {@code -1} if this option is disabled.
-     * @throws SocketException
-     *             if an error occurs while reading the socket option.
-     * @see SocketOptions#SO_LINGER
+     * Returns this socket's {@link SocketOptions#SO_LINGER linger} timeout in seconds, or -1
+     * for no linger (i.e. {@code close} will return immediately).
      */
     public int getSoLinger() throws SocketException {
         checkOpenAndCreate(true);
@@ -482,12 +467,7 @@ public class Socket {
     }
 
     /**
-     * Gets the receive buffer size of this socket.
-     *
-     * @return the current value of the option {@code SocketOptions.SO_RCVBUF}.
-     * @throws SocketException
-     *             if an error occurs while reading the socket option.
-     * @see SocketOptions#SO_RCVBUF
+     * Returns this socket's {@link SocketOptions#SO_RCVBUF receive buffer size}.
      */
     public synchronized int getReceiveBufferSize() throws SocketException {
         checkOpenAndCreate(true);
@@ -495,12 +475,7 @@ public class Socket {
     }
 
     /**
-     * Gets the send buffer size of this socket.
-     *
-     * @return the current value of the option {@code SocketOptions.SO_SNDBUF}.
-     * @throws SocketException
-     *             if an error occurs while reading the socket option.
-     * @see SocketOptions#SO_SNDBUF
+     * Returns this socket's {@link SocketOptions#SO_SNDBUF send buffer size}.
      */
     public synchronized int getSendBufferSize() throws SocketException {
         checkOpenAndCreate(true);
@@ -508,10 +483,7 @@ public class Socket {
     }
 
     /**
-     * Gets the socket {@link SocketOptions#SO_TIMEOUT receive timeout}.
-     *
-     * @throws SocketException
-     *             if an error occurs while reading the socket option.
+     * Returns this socket's {@link SocketOptions#SO_TIMEOUT receive timeout}.
      */
     public synchronized int getSoTimeout() throws SocketException {
         checkOpenAndCreate(true);
@@ -519,13 +491,7 @@ public class Socket {
     }
 
     /**
-     * Gets the setting of the socket option {@code SocketOptions.TCP_NODELAY}.
-     *
-     * @return {@code true} if the {@code SocketOptions.TCP_NODELAY} is enabled,
-     *         {@code false} otherwise.
-     * @throws SocketException
-     *             if an error occurs while reading the socket option.
-     * @see SocketOptions#TCP_NODELAY
+     * Returns this socket's {@code SocketOptions#TCP_NODELAY} setting.
      */
     public boolean getTcpNoDelay() throws SocketException {
         checkOpenAndCreate(true);
@@ -533,13 +499,7 @@ public class Socket {
     }
 
     /**
-     * Sets the state of the {@code SocketOptions.SO_KEEPALIVE} for this socket.
-     *
-     * @param keepAlive
-     *            the state whether this option is enabled or not.
-     * @throws SocketException
-     *             if an error occurs while setting the option.
-     * @see SocketOptions#SO_KEEPALIVE
+     * Sets this socket's {@link SocketOptions#SO_KEEPALIVE} option.
      */
     public void setKeepAlive(boolean keepAlive) throws SocketException {
         if (impl != null) {
@@ -570,15 +530,7 @@ public class Socket {
     }
 
     /**
-     * Sets the send buffer size of this socket.
-     *
-     * @param size
-     *            the buffer size in bytes. This value must be a positive number
-     *            greater than {@code 0}.
-     * @throws SocketException
-     *             if an error occurs while setting the size or the given value
-     *             is an invalid size.
-     * @see SocketOptions#SO_SNDBUF
+     * Sets this socket's {@link SocketOptions#SO_SNDBUF send buffer size}.
      */
     public synchronized void setSendBufferSize(int size) throws SocketException {
         checkOpenAndCreate(true);
@@ -589,15 +541,7 @@ public class Socket {
     }
 
     /**
-     * Sets the receive buffer size of this socket.
-     *
-     * @param size
-     *            the buffer size in bytes. This value must be a positive number
-     *            greater than {@code 0}.
-     * @throws SocketException
-     *             if an error occurs while setting the size or the given value
-     *             is an invalid size.
-     * @see SocketOptions#SO_RCVBUF
+     * Sets this socket's {@link SocketOptions#SO_SNDBUF receive buffer size}.
      */
     public synchronized void setReceiveBufferSize(int size) throws SocketException {
         checkOpenAndCreate(true);
@@ -608,15 +552,8 @@ public class Socket {
     }
 
     /**
-     * Sets the {@link SocketOptions#SO_LINGER} timeout in seconds.
-     *
-     * @param on
-     *            the state whether this option is enabled or not.
-     * @param timeout
-     *            the linger timeout value in seconds.
-     * @throws SocketException
-     *             if an error occurs while setting the option.
-     * @see SocketOptions#SO_LINGER
+     * Sets this socket's {@link SocketOptions#SO_LINGER linger} timeout in seconds.
+     * If {@code on} is false, {@code timeout} is irrelevant.
      */
     public void setSoLinger(boolean on, int timeout) throws SocketException {
         checkOpenAndCreate(true);
@@ -632,15 +569,9 @@ public class Socket {
     }
 
     /**
-     * Sets the {@link SocketOptions#SO_TIMEOUT read timeout} in milliseconds for this socket.
-     * This receive timeout defines the period the socket will block waiting to
-     * receive data before throwing an {@code InterruptedIOException}. The value
-     * {@code 0} (default) is used to set an infinite timeout. To have effect
-     * this option must be set before the blocking method was called.
-     *
-     * @param timeout the timeout in milliseconds or 0 for no timeout.
-     * @throws SocketException
-     *             if an error occurs while setting the option.
+     * Sets this socket's {@link SocketOptions#SO_TIMEOUT read timeout} in milliseconds.
+     * Use 0 for no timeout.
+     * To take effect, this option must be set before the blocking method was called.
      */
     public synchronized void setSoTimeout(int timeout) throws SocketException {
         checkOpenAndCreate(true);
@@ -651,13 +582,7 @@ public class Socket {
     }
 
     /**
-     * Sets the state of the {@code SocketOptions.TCP_NODELAY} for this socket.
-     *
-     * @param on
-     *            the state whether this option is enabled or not.
-     * @throws SocketException
-     *             if an error occurs while setting the option.
-     * @see SocketOptions#TCP_NODELAY
+     * Sets this socket's {@link SocketOptions#TCP_NODELAY} option.
      */
     public void setTcpNoDelay(boolean on) throws SocketException {
         checkOpenAndCreate(true);
@@ -805,11 +730,9 @@ public class Socket {
     }
 
     /**
-     * Gets the local address and port of this socket as a SocketAddress or
-     * {@code null} if the socket is unbound. This is useful on multihomed
+     * Returns the local address and port of this socket as a SocketAddress or
+     * null if the socket is unbound. This is useful on multihomed
      * hosts.
-     *
-     * @return the bound local socket address and port.
      */
     public SocketAddress getLocalSocketAddress() {
         if (!isBound()) {
@@ -819,8 +742,8 @@ public class Socket {
     }
 
     /**
-     * Gets the remote address and port of this socket as a {@code
-     * SocketAddress} or {@code null} if the socket is not connected.
+     * Returns the remote address and port of this socket as a {@code
+     * SocketAddress} or null if the socket is not connected.
      *
      * @return the remote socket address and port.
      */
@@ -1008,13 +931,7 @@ public class Socket {
     }
 
     /**
-     * Sets the state of the {@code SocketOptions.SO_REUSEADDR} for this socket.
-     *
-     * @param reuse
-     *            the state whether this option is enabled or not.
-     * @throws SocketException
-     *             if an error occurs while setting the option.
-     * @see SocketOptions#SO_REUSEADDR
+     * Sets this socket's {@link SocketOptions#SO_REUSEADDR} option.
      */
     public void setReuseAddress(boolean reuse) throws SocketException {
         checkOpenAndCreate(true);
@@ -1022,13 +939,7 @@ public class Socket {
     }
 
     /**
-     * Gets the setting of the socket option {@code SocketOptions.SO_REUSEADDR}.
-     *
-     * @return {@code true} if the {@code SocketOptions.SO_REUSEADDR} is
-     *         enabled, {@code false} otherwise.
-     * @throws SocketException
-     *             if an error occurs while reading the socket option.
-     * @see SocketOptions#SO_REUSEADDR
+     * Returns this socket's {@link SocketOptions#SO_REUSEADDR} setting.
      */
     public boolean getReuseAddress() throws SocketException {
         checkOpenAndCreate(true);
@@ -1036,15 +947,7 @@ public class Socket {
     }
 
     /**
-     * Sets the state of the {@code SocketOptions.SO_OOBINLINE} for this socket.
-     * When this option is enabled urgent data can be received in-line with
-     * normal data.
-     *
-     * @param oobinline
-     *            whether this option is enabled or not.
-     * @throws SocketException
-     *             if an error occurs while setting the option.
-     * @see SocketOptions#SO_OOBINLINE
+     * Sets this socket's {@link SocketOptions#SO_OOBINLINE} option.
      */
     public void setOOBInline(boolean oobinline) throws SocketException {
         checkOpenAndCreate(true);
@@ -1052,13 +955,7 @@ public class Socket {
     }
 
     /**
-     * Gets the setting of the socket option {@code SocketOptions.SO_OOBINLINE}.
-     *
-     * @return {@code true} if the {@code SocketOptions.SO_OOBINLINE} is
-     *         enabled, {@code false} otherwise.
-     * @throws SocketException
-     *             if an error occurs while reading the socket option.
-     * @see SocketOptions#SO_OOBINLINE
+     * Returns this socket's {@link SocketOptions#SO_OOBINLINE} setting.
      */
     public boolean getOOBInline() throws SocketException {
         checkOpenAndCreate(true);
@@ -1066,10 +963,7 @@ public class Socket {
     }
 
     /**
-     * Sets the {@see SocketOptions#IP_TOS} value for every packet sent by this socket.
-     *
-     * @throws SocketException
-     *             if the socket is closed or the option could not be set.
+     * Sets this socket's {@link SocketOptions#IP_TOS} value for every packet sent by this socket.
      */
     public void setTrafficClass(int value) throws SocketException {
         checkOpenAndCreate(true);
@@ -1081,9 +975,6 @@ public class Socket {
 
     /**
      * Returns this socket's {@see SocketOptions#IP_TOS} setting.
-     *
-     * @throws SocketException
-     *             if the socket is closed or the option is invalid.
      */
     public int getTrafficClass() throws SocketException {
         checkOpenAndCreate(true);
@@ -1132,8 +1023,8 @@ public class Socket {
 
     /**
      * Sets performance preferences for connectionTime, latency and bandwidth.
-     * <p>
-     * This method does currently nothing.
+     *
+     * <p>This method does currently nothing.
      *
      * @param connectionTime
      *            the value representing the importance of a short connecting
diff --git a/luni/src/main/java/java/net/SocketOptions.java b/luni/src/main/java/java/net/SocketOptions.java
index 7e3fa3b..ea4a2d7 100644
--- a/luni/src/main/java/java/net/SocketOptions.java
+++ b/luni/src/main/java/java/net/SocketOptions.java
@@ -27,30 +27,35 @@ package java.net;
  * @see DatagramSocketImpl
  */
 public interface SocketOptions {
-
     /**
-     * This option specifies the behavior of the {@code close()} method if there
-     * is still some buffered data to be sent while closing the socket. If the
-     * value of this option is set to {@code 0} the method closes the TCP socket
-     * forcefully and returns immediately. Is this value greater than {@code 0}
-     * the method blocks this time in seconds. If all data could be sent
-     * during this timeout the socket is closed normally otherwise forcefully.
-     * Valid values for this option are in the range 0 to 65535 inclusive. (Larger
+     * Number of seconds to wait when closing a socket if there
+     * is still some buffered data to be sent.
+     *
+     * <p>If this option is set to 0, the TCP socket is closed forcefully and the
+     * call to {@code close} returns immediately.
+     *
+     * <p>If this option is set to a value greater than 0, the value is interpreted
+     * as the number of seconds to wait. If all data could be sent
+     * during this time, the socket is closed normally. Otherwise the connection will be
+     * closed forcefully.
+     *
+     * <p>Valid values for this option are in the range 0 to 65535 inclusive. (Larger
      * timeouts will be treated as 65535s timeouts; roughly 18 hours.)
      */
     public static final int SO_LINGER = 128;
 
     /**
-     * Timeout for blocking accept or read/receive operations (but not write/send operations).
-     * The argument value is specified in milliseconds, with 0 meaning no timeout and negative
-     * values not allowed.
-     * An {@code InterruptedIOException} is thrown if this timeout expires.
+     * Timeout in milliseconds for blocking accept or read/receive operations (but not
+     * write/send operations). A timeout of 0 means no timeout. Negative
+     * timeouts are not allowed.
+     *
+     * <p>An {@code InterruptedIOException} is thrown if this timeout expires.
      */
     public static final int SO_TIMEOUT = 4102;
 
     /**
-     * This option specifies whether data is sent immediately on this socket, as
-     * a side-effect though, this could lead to a low packet efficiency. The
+     * Whether data is sent immediately on this socket.
+     * As a side-effect this could lead to low packet efficiency. The
      * socket implementation uses the Nagle's algorithm to try to reach a higher
      * packet efficiency if this option is disabled.
      */
@@ -61,8 +66,8 @@ public interface SocketOptions {
     // For 7 see PlainDatagramSocketImpl
 
     /**
-     * This option specifies the interface which is used to send multicast
-     * packets. It's only available on a {@code MulticastSocket}.
+     * The interface used to send multicast packets.
+     * This option is only available on a {@link MulticastSocket}.
      */
     public static final int IP_MULTICAST_IF = 16;
 
@@ -83,12 +88,19 @@ public interface SocketOptions {
     // 10 not currently used
 
     /**
-     * Buffer size of the outgoing channel.
+     * The size in bytes of a socket's send buffer. This must be an integer greater than 0.
+     * This is a hint to the kernel; the kernel may use a larger buffer.
+     *
+     * <p>For datagram sockets, it is implementation-defined whether packets larger than
+     * this size can be sent.
      */
     public static final int SO_SNDBUF = 4097;
 
     /**
-     * Buffer size of the incoming channel.
+     * The size in bytes of a socket's receive buffer. This must be an integer greater than 0.
+     * This is a hint to the kernel; the kernel may use a larger buffer.
+     *
+     * <p>For datagram sockets, packets larger than this value will be discarded.
      */
     public static final int SO_RCVBUF = 4098;
 
@@ -135,7 +147,7 @@ public interface SocketOptions {
     public static final int SO_BROADCAST = 32;
 
     /**
-     * This option specifies whether sending TCP urgent data is supported on
+     * This boolean option specifies whether sending TCP urgent data is supported on
      * this socket or not.
      */
     public static final int SO_OOBINLINE = 4099;
diff --git a/luni/src/main/java/java/net/SocketPermission.java b/luni/src/main/java/java/net/SocketPermission.java
index 977e310..a4dd942 100644
--- a/luni/src/main/java/java/net/SocketPermission.java
+++ b/luni/src/main/java/java/net/SocketPermission.java
@@ -427,7 +427,7 @@ public final class SocketPermission extends Permission implements Serializable {
             }
             return host.toLowerCase();
         }
-            // maybe ipv6
+        // maybe IPv6
         boolean isFirstBracket = (host.charAt(0) == '[');
         if (!isFirstBracket) {
             // No bracket, should be in full form