harmony-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From telli...@apache.org
Subject svn commit: r772095 [2/6] - /harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/
Date Wed, 06 May 2009 08:33:22 GMT
Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/DatagramSocketImpl.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/DatagramSocketImpl.java?rev=772095&r1=772094&r2=772095&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/DatagramSocketImpl.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/DatagramSocketImpl.java Wed May  6 08:33:17 2009
@@ -24,12 +24,18 @@
 import org.apache.harmony.luni.platform.Platform;
 
 /**
- * The abstract superclass of datagram & multicast socket implementations.
+ * The abstract superclass for datagram and multicast socket implementations.
  */
 public abstract class DatagramSocketImpl implements SocketOptions {
 
+    /**
+     * File descriptor that is used to address this socket.
+     */
     protected FileDescriptor fd;
 
+    /**
+     * The number of the local port to which this socket is bound.
+     */
     protected int localPort;
 
     /**
@@ -40,46 +46,48 @@
     }
 
     /**
-     * Bind the datagram socket to the nominated localhost/port. Sockets must be
+     * Binds the datagram socket to the given localhost/port. Sockets must be
      * bound prior to attempting to send or receive data.
      * 
      * @param port
-     *            the port on the localhost to bind
+     *            the port on the localhost to bind.
      * @param addr
-     *            the address on the multihomed localhost to bind
-     * 
-     * @exception SocketException
-     *                if an error occurred during bind, such as if the port was
-     *                already bound
+     *            the address on the multihomed localhost to bind.
+     * @throws SocketException
+     *                if an error occurs while binding, for example, if the port
+     *                has been already bound.
      */
     protected abstract void bind(int port, InetAddress addr)
             throws SocketException;
 
     /**
-     * Close the socket.
+     * Closes this socket.
      */
     protected abstract void close();
 
     /**
      * This method allocates the socket descriptor in the underlying operating
      * system.
+     *
+     * @throws SocketException
+     *             if an error occurs while creating the socket.
      */
     protected abstract void create() throws SocketException;
 
     /**
-     * Answer the FileDescriptor, which will be invalid if the socket is closed
-     * or not bound.
+     * Gets the {@code FileDescriptor} of this datagram socket, which is invalid
+     * if the socket is closed or not bound.
      * 
-     * @return FileDescriptor the socket file descriptor
+     * @return the current file descriptor of this socket.
      */
     protected FileDescriptor getFileDescriptor() {
         return fd;
     }
 
     /**
-     * Answer the local address to which the socket is bound.
+     * Gets the local address to which the socket is bound.
      * 
-     * @return InetAddress the local address to which the socket is bound.
+     * @return the local address to which the socket is bound.
      */
     InetAddress getLocalAddress() {
         return Platform.getNetworkSystem().getSocketLocalAddress(fd,
@@ -87,174 +95,192 @@
     }
 
     /**
-     * Answer the local port. If the socket was bound to any available port, as
-     * flagged by a <code>localPort</code> value of -1, query the IP stack.
+     * Gets the local port of this socket.
      * 
-     * @return int the local port to which the socket is bound.
+     * @return the local port to which this socket is bound.
      */
     protected int getLocalPort() {
         return localPort;
     }
 
     /**
-     * Answer the nominated socket option.
+     * Gets the value for the specified socket option.
      * 
      * @param optID
-     *            the socket option to retrieve
-     * @return Object the option value
-     * @exception SocketException
-     *                thrown if an error occurs while accessing the option
+     *            the ID of the socket option to be retrieved.
+     * @return the requested option value.
+     * @throws SocketException
+     *                if an error occurs while accessing the option.
      */
     public abstract Object getOption(int optID) throws SocketException;
 
     /**
-     * Answer the time-to-live (TTL) for multicast packets sent on this socket.
+     * Gets the time-to-live (TTL) for multicast packets sent on this socket.
      * 
-     * @return java.net.InetAddress
+     * @return the time-to-live option as a byte value.
      * @throws IOException
-     *             The exception description.
-     * @deprecated Replaced by getTimeToLive
+     *             if an error occurs while getting the time-to-live option
+     *             value.
+     * @deprecated Replaced by {@link #getTimeToLive}
      * @see #getTimeToLive()
      */
     @Deprecated
     protected abstract byte getTTL() throws IOException;
 
     /**
-     * Answer the time-to-live (TTL) for multicast packets sent on this socket.
-     * 
-     * @return int
+     * Gets the time-to-live (TTL) for multicast packets sent on this socket.
+     * The TTL option defines how many routers a packet may be pass before it is
+     * discarded.
+     *
+     * @return the time-to-live option as an integer value.
      * @throws IOException
-     *             The exception description.
+     *             if an error occurs while getting the time-to-live option
+     *             value.
      */
     protected abstract int getTimeToLive() throws IOException;
 
     /**
-     * Add this socket to the multicast group. A socket must join a group before
-     * data may be received. A socket may be a member of multiple groups but may
-     * join any group once.
+     * Adds this socket to the multicast group {@code addr}. A socket must join
+     * a group before being able to receive data. Further, a socket may be a
+     * member of multiple groups but may join any group only once.
      * 
      * @param addr
-     *            the multicast group to be joined
+     *            the multicast group to which this socket has to be joined.
      * @throws IOException
-     *             may be thrown while joining a group
+     *             if an error occurs while joining the specified multicast
+     *             group.
      */
     protected abstract void join(InetAddress addr) throws IOException;
 
     /**
-     * Add this socket to the multicast group. A socket must join a group before
-     * data may be received. A socket may be a member of multiple groups but may
-     * join any group once.
+     * Adds this socket to the multicast group {@code addr}. A socket must join
+     * a group before being able to receive data. Further, a socket may be a
+     * member of multiple groups but may join any group only once.
      * 
      * @param addr
-     *            the multicast group to be joined
+     *            the multicast group to which this socket has to be joined.
      * @param netInterface
-     *            the network interface on which the addresses should be dropped
+     *            the local network interface which will receive the multicast
+     *            datagram packets.
      * @throws IOException
-     *             may be thrown while joining a group
+     *             if an error occurs while joining the specified multicast
+     *             group.
      */
     protected abstract void joinGroup(SocketAddress addr,
             NetworkInterface netInterface) throws IOException;
 
     /**
-     * Remove the socket from the multicast group.
+     * Removes this socket from the multicast group {@code addr}.
      * 
      * @param addr
-     *            the multicast group to be left
+     *            the multicast group to be left.
      * @throws IOException
-     *             May be thrown while leaving the group
+     *             if an error occurs while leaving the group or no multicast
+     *             address was assigned.
      */
     protected abstract void leave(InetAddress addr) throws IOException;
 
     /**
-     * Remove the socket from the multicast group.
+     * Removes this socket from the multicast group {@code addr}.
      * 
      * @param addr
-     *            the multicast group to be left
+     *            the multicast group to be left.
      * @param netInterface
-     *            the network interface on which the addresses should be dropped
+     *            the local network interface on which this socket has to be
+     *            removed.
      * @throws IOException
-     *             May be thrown while leaving the group
+     *             if an error occurs while leaving the group.
      */
     protected abstract void leaveGroup(SocketAddress addr,
             NetworkInterface netInterface) throws IOException;
 
     /**
-     * Peek at the incoming packet to this socket and answer the sender's
-     * address into <code>sender</code>. The method will block until a packet
-     * is received or timeout expires and returns the sender's port.
-     * 
-     * @exception IOException
-     *                if a read error or timeout occurs
+     * Peeks at the incoming packet to this socket and returns the address of
+     * the {@code sender}. The method will block until a packet is received or
+     * timeout expires.
+     * 
+     * @param sender
+     *            the origin address of a packet.
+     * @return the address of {@code sender} as an integer value.
+     * @throws IOException
+     *                if an error or a timeout occurs while reading the address.
      */
     protected abstract int peek(InetAddress sender) throws IOException;
 
     /**
-     * Receive data into the supplied datagram packet. This call will block
-     * until either data is received or, if a timeout is set, the timeout
-     * expires. If the timeout expires, the InterruptedIOException is thrown.
+     * Receives data and stores it in the supplied datagram packet {@code pack}.
+     * This call will block until either data has been received or, if a timeout
+     * is set, the timeout has expired. If the timeout expires an {@code
+     * InterruptedIOException} is thrown.
      * 
-     * @exception IOException
-     *                if a read error or timeout occurs
+     * @param pack
+     *            the datagram packet container to fill in the received data.
+     * @throws IOException
+     *                if an error or timeout occurs while receiving data.
      */
     protected abstract void receive(DatagramPacket pack) throws IOException;
 
     /**
-     * Sends the supplied datagram packet. The packet contains the destination
-     * host & port.
+     * Sends the given datagram packet {@code pack}. The packet contains the
+     * data and the address and port information of the target host as well.
      * 
      * @param pack
-     *            DatagramPacket to send
-     * 
-     * @exception IOException
-     *                if a write error occurs
+     *            the datagram packet to be sent.
+     * @throws IOException
+     *                if an error occurs while sending the packet.
      */
     protected abstract void send(DatagramPacket pack) throws IOException;
 
     /**
-     * Set the nominated socket option.
+     * Sets the value for the specified socket option.
      * 
      * @param optID
-     *            the socket option to set
+     *            the ID of the socket option to be set.
      * @param val
-     *            the option value
-     * @exception SocketException
-     *                thrown if an error occurs while setting the option
+     *            the value of the option.
+     * @throws SocketException
+     *                if an error occurs while setting the option.
      */
     public abstract void setOption(int optID, Object val)
             throws SocketException;
 
     /**
-     * Set the time-to-live (TTL) for multicast packets sent on this socket.
+     * Sets the time-to-live (TTL) option for multicast packets sent on this
+     * socket.
      * 
      * @param ttl
-     *            the time-to-live, 0<ttl<= 255
-     * @throws IOException The exception thrown while setting the TTL
+     *            the time-to-live option value. Valid values are 0 &lt; ttl
+     *            &lt;= 255.
+     * @throws IOException
+     *             if an error occurs while setting the option.
      */
     protected abstract void setTimeToLive(int ttl) throws IOException;
 
     /**
-     * Set the time-to-live (TTL) for multicast packets sent on this socket.
+     * Sets the time-to-live (TTL) option for multicast packets sent on this
+     * socket.
      * 
      * @param ttl
-     *            the time-to-live, 0<ttl<= 255
-     * @throws IOException The exception thrown while setting the TTL
-     * @deprecated Replaced by setTimeToLive
+     *            the time-to-live option value. Valid values are 0 &lt; ttl
+     *            &lt;= 255.
+     * @throws IOException
+     *             if an error occurs while setting the option.
+     * @deprecated Replaced by {@link #setTimeToLive}
      * @see #setTimeToLive(int)
      */
     @Deprecated
     protected abstract void setTTL(byte ttl) throws IOException;
 
     /**
-     * Connect the socket to the specified remote address and port.
+     * Connects this socket to the specified remote address and port.
      * 
      * @param inetAddr
-     *            the remote address
+     *            the address of the target host which has to be connected.
      * @param port
-     *            the remote port
-     * 
-     * @exception SocketException
-     *                possibly thrown, if the datagram socket cannot be
-     *                connected to the specified remote address and port
+     *            the port on the target host which has to be connected.
+     * @throws SocketException
+     *                if the datagram socket cannot be connected to the
+     *                specified remote address and port.
      */
     protected void connect(InetAddress inetAddr, int port)
             throws SocketException {
@@ -262,26 +288,24 @@
     }
 
     /**
-     * Disconnect the socket from the remote address and port.
+     * Disconnects this socket from the remote host.
      */
     protected void disconnect() {
         // do nothing
     }
 
     /**
-     * Receive data into the supplied datagram packet by peeking. The data is
-     * not removed and will be received by another peekData() or receive() call.
-     * 
-     * This call will block until either data is received or, if a timeout is
-     * set, the timeout expires.
+     * Receives data into the supplied datagram packet by peeking. The data is
+     * not removed from socket buffer and can be received again by another
+     * {@code peekData()} or {@code receive()} call. This call blocks until
+     * either data has been received or, if a timeout is set, the timeout has
+     * been expired.
      * 
      * @param pack
-     *            the DatagramPacket used to store the data
-     * 
-     * @return the port the packet was received from
-     * 
-     * @exception IOException
-     *                if an error occurs
+     *            the datagram packet used to store the data.
+     * @return the port the packet was received from.
+     * @throws IOException
+     *                if an error occurs while peeking at the data.
      */
     protected abstract int peekData(DatagramPacket pack) throws IOException;
 }

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/DatagramSocketImplFactory.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/DatagramSocketImplFactory.java?rev=772095&r1=772094&r2=772095&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/DatagramSocketImplFactory.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/DatagramSocketImplFactory.java Wed May  6 08:33:17 2009
@@ -19,14 +19,17 @@
 
 /**
  * This interface defines a factory for datagram socket implementations. It is
- * used by the class <code>DatagramSocket</code> to create datagram socket
- * implementations.
+ * used by the class {@code DatagramSocket} to create a new datagram socket
+ * implementation.
+ * 
+ * @see DatagramSocket
  */
 public interface DatagramSocketImplFactory {
+    
     /**
-     * Creates a new <code>SocketImpl</code> instance.
+     * Creates a new {@code DatagramSocketImpl} instance.
      * 
-     * @return SocketImpl
+     * @return the new datagram socket implementation.
      */
     DatagramSocketImpl createDatagramSocketImpl();
 }

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/FileNameMap.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/FileNameMap.java?rev=772095&r1=772094&r2=772095&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/FileNameMap.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/FileNameMap.java Wed May  6 08:33:17 2009
@@ -19,8 +19,8 @@
 
 /**
  * Defines a scheme for mapping a filename type to a MIME content type. Mainly
- * used by <code>URLStreamHandler</code> for determining the right content
- * handler to handle the resource.
+ * used by {@code URLStreamHandler} for determining the right content handler to
+ * handle the resource.
  * 
  * @see ContentHandler
  * @see URLConnection#getFileNameMap()
@@ -30,13 +30,11 @@
 public interface FileNameMap {
 
     /**
-     * Determines the MIME types for a file <code>fileName</code> of a
-     * <code>URL</code>.
+     * Determines the MIME type for a file {@code fileName} of a URL.
      * 
      * @param fileName
      *            the name of the file to consider.
-     * 
-     * @return the mime type
+     * @return the appropriate MIME type of the given file.
      */
     public String getContentTypeFor(String fileName);
 }

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/HttpRetryException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/HttpRetryException.java?rev=772095&r1=772094&r2=772095&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/HttpRetryException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/HttpRetryException.java Wed May  6 08:33:17 2009
@@ -19,7 +19,8 @@
 import java.io.IOException;
 
 /**
- * The exception to be thrown when a request cannot be retried.
+ * If a HTTP request has to be retried, this exception will be thrown if the
+ * request cannot be retried automatically.
  */
 public class HttpRetryException extends IOException {
 
@@ -30,12 +31,13 @@
     private String location = null;
 
     /**
-     * new a HttpRetryException by given detail message and responseCode
+     * Creates a new {@code HttpRetryException} instance with the specified
+     * response code and the given detail message.
      * 
      * @param detail
-     *            detail for this exception
+     *            the detail message for this exception.
      * @param code
-     *            http response code to return
+     *            the HTTP response code from target host.
      */
     public HttpRetryException(String detail, int code) {
         super(detail);
@@ -43,16 +45,16 @@
     }
 
     /**
-     * new a HttpRetryException by given detail message, responseCode and the
-     * Location response header
+     * Creates a new {@code HttpRetryException} instance with the specified
+     * response code, the given detail message and the value of the location
+     * field from the response header.
      * 
      * @param detail
-     *            detail for this exception
+     *            the detail message for this exception.
      * @param code
-     *            http response code to return
+     *            the HTTP response code from target host.
      * @param location
-     *            the error resulted from redirection, the Location header can
-     *            be recorded
+     *            the destination URL of the redirection.
      */
     public HttpRetryException(String detail, int code, String location) {
         super(detail);
@@ -61,21 +63,27 @@
     }
 
     /**
-     * @return the Location header recorded
+     * Gets the location value.
+     *
+     * @return the stored location from the HTTP header.
      */
     public String getLocation() {
         return location;
     }
 
     /**
-     * @return the detail reason for this exception
+     * Gets the detail message.
+     *
+     * @return the detail message.
      */
     public String getReason() {
         return getMessage();
     }
 
     /**
-     * @return a http response code
+     * Gets the response code.
+     *
+     * @return the HTTP response code.
      */
     public int responseCode() {
         return responseCode;

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/HttpURLConnection.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/HttpURLConnection.java?rev=772095&r1=772094&r2=772095&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/HttpURLConnection.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/HttpURLConnection.java Wed May  6 08:33:17 2009
@@ -22,8 +22,8 @@
 import org.apache.harmony.luni.util.Msg;
 
 /**
- * This abstract subclass of <code>URLConnection</code> defines method for
- * managing HTTP connection according to the description given by RFC 2068
+ * This abstract subclass of {@code URLConnection} defines methods for managing
+ * HTTP connection according to the description given by RFC 2068.
  * 
  * @see ContentHandler
  * @see URL
@@ -35,21 +35,49 @@
     private String methodTokens[] = { "GET", "DELETE", "HEAD", "OPTIONS",
             "POST", "PUT", "TRACE" };
 
-    // Request method, DEFAULT: "GET"
+   /**
+     * The HTTP request method of this {@code HttpURLConnection}. The default
+     * value is {@code "GET"}.
+     */
     protected String method = "GET"; //$NON-NLS-1$
 
-    // Response code obtained from the request
+    /**
+     * The status code of the response obtained from the HTTP request. The
+     * default value is {@code -1}.
+     * <p>
+     * <li>1xx: Informational</li>
+     * <li>2xx: Success</li>
+     * <li>3xx: Relocation/Redirection</li>
+     * <li>4xx: Client Error</li>
+     * <li>5xx: Server Error</li>
+     */
     protected int responseCode = -1;
 
-    // Response message, corresponds to the response code
+    /**
+     * The HTTP response message which corresponds to the response code.
+     */
     protected String responseMessage;
 
+    /**
+     * Flag to define whether the protocol will automatically follow redirects
+     * or not. The default value is {@code true}.
+     */
     protected boolean instanceFollowRedirects = followRedirects;
 
     private static boolean followRedirects = true;
 
+    /**
+     * If the HTTP chunked encoding is enabled this parameter defines the
+     * chunk-length. Default value is {@code -1} that means the chunked encoding
+     * mode is disabled.
+     */
     protected int chunkLength = -1;
 
+    /**
+     * If using HTTP fixed-length streaming mode this parameter defines the
+     * fixed length of content. Default value is {@code -1} that means the
+     * fixed-length streaming mode is disabled.
+     */
     protected int fixedContentLength = -1;
 
     private final static int DEFAULT_CHUNK_LENGTH = 1024;
@@ -209,7 +237,9 @@
     public final static int HTTP_SEE_OTHER = 303;
 
     /**
-     * @deprecated Use HTTP_INTERNAL_ERROR
+     * Numeric status code, 500: Internal error
+     *
+     * @deprecated Use {@link #HTTP_INTERNAL_ERROR}
      */
     @Deprecated
     public final static int HTTP_SERVER_ERROR = 500;
@@ -240,12 +270,11 @@
     public final static int HTTP_VERSION = 505;
 
     /**
-     * Constructs a <code>HttpURLConnection</code> pointing to the resource
-     * specified by the <code>URL</code>.
+     * Constructs a new {@code HttpURLConnection} instance pointing to the
+     * resource specified by the {@code url}.
      * 
      * @param url
-     *            the URL of this connection
-     * 
+     *            the URL of this connection.
      * @see URL
      * @see URLConnection
      */
@@ -254,7 +283,7 @@
     }
 
     /**
-     * Closes the connection with the HTTP server
+     * Closes the connection to the HTTP server.
      * 
      * @see URLConnection#connect()
      * @see URLConnection#connected
@@ -262,11 +291,9 @@
     public abstract void disconnect();
 
     /**
-     * Answers a input stream from the server in the case of error such as the
-     * requested file (txt, htm, html) is not found on the remote server.
-     * <p>
-     * If the content type is not what stated above,
-     * <code>FileNotFoundException</code> is thrown.
+     * Returns an input stream from the server in the case of an error such as
+     * the requested file has not been found on the remote server. This stream
+     * can be used to read the data the server will send back.
      * 
      * @return the error input stream returned by the server.
      */
@@ -275,12 +302,11 @@
     }
 
     /**
-     * Answers the value of <code>followRedirects</code> which indicates if
-     * this connection will follows a different URL redirected by the server. It
-     * is enabled by default.
-     * 
-     * @return The value of the flag
+     * Returns the value of {@code followRedirects} which indicates if this
+     * connection follows a different URL redirected by the server. It is
+     * enabled by default.
      * 
+     * @return the value of the flag.
      * @see #setFollowRedirects
      */
     public static boolean getFollowRedirects() {
@@ -288,12 +314,12 @@
     }
 
     /**
-     * Answers the permission object (in this case, SocketPermission) with the
-     * host and the port number as the target name and "resolve, connect" as the
-     * action list.
-     * 
-     * @return the permission object required for this connection
+     * Returns the permission object (in this case {@code SocketPermission})
+     * with the host and the port number as the target name and {@code
+     * "resolve, connect"} as the action list. If the port number of this URL
+     * instance is lower than {@code 0} the port will be set to {@code 80}.
      * 
+     * @return the permission object required for this connection.
      * @throws IOException
      *             if an IO exception occurs during the creation of the
      *             permission object.
@@ -309,12 +335,11 @@
     }
 
     /**
-     * Answers the request method which will be used to make the request to the
+     * Returns the request method which will be used to make the request to the
      * remote HTTP server. All possible methods of this HTTP implementation is
      * listed in the class definition.
      * 
-     * @return the request method string
-     * 
+     * @return the request method string.
      * @see #method
      * @see #setRequestMethod
      */
@@ -323,13 +348,11 @@
     }
 
     /**
-     * Answers the response code returned by the remote HTTP server
-     * 
-     * @return the response code, -1 if no valid response code
+     * Returns the response code returned by the remote HTTP server.
      * 
+     * @return the response code, -1 if no valid response code.
      * @throws IOException
      *             if there is an IO error during the retrieval.
-     * 
      * @see #getResponseMessage
      */
     public int getResponseCode() throws IOException {
@@ -357,15 +380,12 @@
     }
 
     /**
-     * Answers the response message returned the remote HTTP server
-     * 
-     * @return the response message. <code>null</code> if such response exists
+     * Returns the response message returned by the remote HTTP server.
      * 
+     * @return the response message. {@code null} if no such response exists.
      * @throws IOException
-     *             if there is an IO error during the retrieval.
-     * 
+     *             if there is an error during the retrieval.
      * @see #getResponseCode()
-     * @see IOException
      */
     public String getResponseMessage() throws IOException {
         if (responseMessage != null) {
@@ -378,12 +398,11 @@
     /**
      * Sets the flag of whether this connection will follow redirects returned
      * by the remote server. This method can only be called with the permission
-     * from the security manager
+     * from the security manager.
      * 
      * @param auto
-     *            The value to set
-     * 
-     * @see java.lang.SecurityManager#checkSetFactory()
+     *            the value to enable or disable this option.
+     * @see SecurityManager#checkSetFactory()
      */
     public static void setFollowRedirects(boolean auto) {
         SecurityManager security = System.getSecurityManager();
@@ -398,12 +417,10 @@
      * This method can only be called before the connection is made.
      * 
      * @param method
-     *            The <code>non-null</code> string representing the method
-     * 
+     *            the string representing the method to be used.
      * @throws ProtocolException
-     *             Thrown when this is called after connected, or the method is
-     *             not supported by this HTTP implementation.
-     * 
+     *             if this is called after connected, or the method is not
+     *             supported by this HTTP implementation.
      * @see #getRequestMethod()
      * @see #method
      */
@@ -424,26 +441,28 @@
     }
 
     /**
-     * Answers if this connection uses proxy.
+     * Returns whether this connection uses a proxy server or not.
      * 
-     * @return true if this connection supports proxy, false otherwise.
+     * @return {@code true} if this connection passes a proxy server, false
+     *         otherwise.
      */
     public abstract boolean usingProxy();
 
     /**
-     * Answers if this connection follows redirects.
+     * Returns whether this connection follows redirects.
      * 
-     * @return true if this connection follows redirects, false otherwise.
+     * @return {@code true} if this connection follows redirects, false
+     *         otherwise.
      */
     public boolean getInstanceFollowRedirects() {
         return instanceFollowRedirects;
     }
 
     /**
-     * Sets if this connection follows redirects.
+     * Sets whether this connection follows redirects.
      * 
      * @param followRedirects
-     *            true if this connection should follows redirects, false
+     *            {@code true} if this connection will follows redirects, false
      *            otherwise.
      */
     public void setInstanceFollowRedirects(boolean followRedirects) {
@@ -451,16 +470,17 @@
     }
 
     /**
-     * Answers the date value in the form of milliseconds since epoch
-     * corresponding to the field <code>field</code>. Answers
-     * <code>defaultValue</code> if no such field can be found in the response
-     * header.
+     * Returns the date value in milliseconds since {@code 01.01.1970, 00:00h}
+     * corresponding to the header field {@code field}. The {@code defaultValue}
+     * will be returned if no such field can be found in the response header.
      * 
      * @param field
-     *            the field in question
+     *            the header field name.
      * @param defaultValue
-     *            the default value if no field is found
-     * @return milliseconds since epoch
+     *            the default value to use if the specified header field wont be
+     *            found.
+     * @return the header field represented in milliseconds since January 1,
+     *         1970 GMT.
      */
     @Override
     public long getHeaderFieldDate(String field, long defaultValue) {
@@ -468,17 +488,17 @@
     }
 
     /**
-     * If length of a HTTP request body is known ahead, sets fixed length to
+     * If the length of a HTTP request body is known ahead, sets fixed length to
      * enable streaming without buffering. Sets after connection will cause an
      * exception.
      * 
-     * @see <code>setChunkedStreamingMode</code>
+     * @see #setChunkedStreamingMode
      * @param contentLength
-     *            the fixed length of the HTTP request body
+     *            the fixed length of the HTTP request body.
      * @throws IllegalStateException
-     *             if already connected or other mode already set
+     *             if already connected or an other mode already set.
      * @throws IllegalArgumentException
-     *             if contentLength is less than zero
+     *             if {@code contentLength} is less than zero.
      */
     public void setFixedLengthStreamingMode(int contentLength) {
         if (super.connected) {
@@ -494,16 +514,16 @@
     }
 
     /**
-     * If length of a HTTP request body is NOT known ahead, enable chunked
-     * transfer encoding to enable streaming without buffering. Notice that not
-     * all http servers support this mode. Sets after connection will cause an
+     * If the length of a HTTP request body is NOT known ahead, enable chunked
+     * transfer encoding to enable streaming with buffering. Notice that not all
+     * http servers support this mode. Sets after connection will cause an
      * exception.
      * 
-     * @see <code>setFixedLengthStreamingMode</code>
+     * @see #setFixedLengthStreamingMode
      * @param chunklen
-     *            the length of a chunk
+     *            the length of a chunk.
      * @throws IllegalStateException
-     *             if already connected or other mode already set
+     *             if already connected or an other mode already set.
      */
     public void setChunkedStreamingMode(int chunklen) {
         if (super.connected) {

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/Inet4Address.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/Inet4Address.java?rev=772095&r1=772094&r2=772095&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/Inet4Address.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/Inet4Address.java Wed May  6 08:33:17 2009
@@ -19,6 +19,16 @@
 
 import java.io.ObjectStreamException;
 
+/**
+ * This class represents a 32 bit long IPv4 address. The most common textual
+ * representation of an IPv4 address follows the pattern {@code b.b.b.b} where
+ * each {@code b} represents one of the four bytes. If only three parts are
+ * specified ({@code b.b.bb} ), the last part is then 16 bit long, the address
+ * represents a class B network address as <i>128.net.host</i>. A two part
+ * address ({@code b.bbb} ) allows to represent a class A network address as
+ * <i>net.host</i>. If there is only one part ({@code bbbb} ) the address is
+ * represented without any byte rearrangement.
+ */
 public final class Inet4Address extends InetAddress {
 
     private static final long serialVersionUID = 3286316764910316507L;
@@ -33,10 +43,11 @@
     }
 
     /**
-     * Answers true if the address is a multicast address. Valid IPv4 multicast
-     * addresses are prefixed with 1110 = 0xE
+     * Returns whether the represented address is a multicast address or not.
+     * Valid IPv4 multicast addresses are prefixed with 1110 = 0xE.
      * 
-     * @return boolean
+     * @return {@code true} if this instance represents a multicast address,
+     *         {@code false} otherwise.
      */
     @Override
     public boolean isMulticastAddress() {
@@ -44,9 +55,11 @@
     }
 
     /**
-     * Answers if the address is the ANY Address
+     * Returns whether the represented address is the local wildcard ANY address
+     * or not.
      * 
-     * @return boolean
+     * @return {@code true} if this instance represents the wildcard ANY
+     *         address, {@code false} otherwise.
      */
     @Override
     public boolean isAnyLocalAddress() {
@@ -59,10 +72,11 @@
     }
 
     /**
-     * Answers true if the address is a loopback address. Loopback ipv4
-     * addresses are prefixed with: 011111111 = 127
+     * Returns whether the represented address is a loopback address or not.
+     * Loopback IPv4 addresses are prefixed with: 011111111 = 127.
      * 
-     * @return boolean
+     * @return {@code true} if this instance represents a lookback address,
+     *         {@code false} otherwise.
      */
     @Override
     public boolean isLoopbackAddress() {
@@ -70,13 +84,15 @@
     }
 
     /**
-     * Answers whether this address has link-local scope.
-     * 
-     * RFC 3484 Default Address Selection for Internet Protocol version 6 (IPv6)
-     * states IPv4 auto-configuration addresses, prefix 169.254/16, IPv4
-     * loopback addresses, prefix 127/8, are assigned link-local scope.
-     * 
-     * @return boolean
+     * Returns whether this address has a link-local scope or not.
+     * <p>
+     * RFC 3484 <br>
+     * Default Address Selection for Internet Protocol Version 6 (IPv6) states
+     * IPv4 auto-configuration addresses, prefix 169.254/16, IPv4 loopback
+     * addresses, prefix 127/8, are assigned link-local scope.
+     *
+     * @return {@code true} if this instance represents a link-local address,
+     *         {@code false} otherwise.
      */
     @Override
     public boolean isLinkLocalAddress() {
@@ -86,12 +102,15 @@
     }
 
     /**
-     * Answers whether this address has site-local scope. RFC 3484 Default
-     * Address Selection for Internet Protocol version 6 (IPv6) states IPv4
-     * private addresses, prefixes 10/8, 172.16/12, and 192.168/16, are assigned
-     * site-local scope.
+     * Returns whether this address has a site-local scope or not.
+     * <p>
+     * RFC 3484 <br>
+     * Default Address Selection for Internet Protocol Version 6 (IPv6) states
+     * IPv4 private addresses, prefixes 10/8, 172.16/12, and 192.168/16, are
+     * assigned site-local scope.
      * 
-     * @return boolean
+     * @return {@code true} if this instance represents a site-local address,
+     *         {@code false} otherwise.
      */
     @Override
     public boolean isSiteLocalAddress() {
@@ -102,11 +121,11 @@
     }
 
     /**
-     * Answers true if an address is a global multicast address. Valid MCGlobal
-     * IPv4 addresses are 224.0.1.0 - 238.255.255.255
+     * Returns whether the address is a global multicast address or not. Valid
+     * MCGlobal IPv4 addresses are 224.0.1.0 - 238.255.255.255.
      * 
-     * @return boolean true, if the address is in the global multicast group,
-     *         false otherwise
+     * @return {@code true} if the address is in the global multicast group,
+     *         {@code false} otherwise.
      */
     @Override
     public boolean isMCGlobal() {
@@ -140,10 +159,11 @@
     }
 
     /**
-     * Answers false for all IPv4 addresses. There are no valid IPv4 Node-local
-     * addresses
+     * Returns whether the address has a node-local scope or not. This method
+     * returns always {@code false} because there are no valid IPv4 node-local
+     * addresses.
      * 
-     * @return boolean
+     * @return {@code false} for all IPv4 addresses.
      */
     @Override
     public boolean isMCNodeLocal() {
@@ -151,11 +171,12 @@
     }
 
     /**
-     * Answers true if the address is a link-local address.The valid range for
-     * IPv4 link-local addresses is: 224.0.0.0 to 239.0.0.255 Hence a mask of
-     * 111000000000000000000000 = 0xE00000
+     * Returns whether the address is a link-local multicast address or not. The
+     * valid range for IPv4 link-local addresses is: 224.0.0.0 to 239.0.0.255
+     * Hence a mask of 111000000000000000000000 = 0xE00000.
      * 
-     * @return boolean
+     * @return {@code true} if this instance represents a link-local address,
+     *         {@code false} otherwise.
      */
     @Override
     public boolean isMCLinkLocal() {
@@ -163,11 +184,12 @@
     }
 
     /**
-     * Answers true if the address is a site-local address.The valid range for
-     * IPv4 site-local addresses is: 239.255.0.0 to 239.255.255.255 Hence a mask
-     * of 11101111 11111111 = 0xEFFF.
+     * Returns whether the address is a site-local multicast address or not. The
+     * valid range for IPv4 site-local addresses is: 239.255.0.0 to
+     * 239.255.255.255 Hence a mask of 11101111 11111111 = 0xEFFF.
      * 
-     * @return boolean
+     * @return {@code true} if this instance represents a site-local address,
+     *         {@code false} otherwise.
      */
     @Override
     public boolean isMCSiteLocal() {
@@ -175,12 +197,13 @@
     }
 
     /**
-     * Answers true if the address is a organization-local address. The valid
-     * range for IPv4 org-local addresses is: 239.192.0.0 to 239.195.255.255
-     * Hence masks of 11101111 11000000 to 11101111 11000011 are valid. 0xEFC0
-     * to 0xEFC3
+     * Returns whether the address is a organization-local multicast address or
+     * not. The valid range for IPv4 organization-local addresses is:
+     * 239.192.0.0 to 239.195.255.255 Hence masks of 11101111 11000000 to
+     * 11101111 11000011 are valid. 0xEFC0 to 0xEFC3
      * 
-     * @return true if org local address, false otherwise
+     * @return {@code true} if this instance represents a organization-local
+     *         address, {@code false} otherwise.
      */
     @Override
     public boolean isMCOrgLocal() {
@@ -189,9 +212,9 @@
     }
 
     /**
-     * Returns a String representation of the IP address.
+     * Returns a textual representation of this IP address.
      * 
-     * @return Host address
+     * @return the textual representation of this host address.
      */
     @Override
     public String getHostAddress() {
@@ -206,9 +229,9 @@
     }
 
     /**
-     * Overrides the basic hashcode function.
+     * Gets the hashcode of the represented IP address.
      * 
-     * @return the hash code
+     * @return the appropriate hashcode value.
      */
     @Override
     public int hashCode() {
@@ -216,10 +239,13 @@
     }
 
     /**
-     * Returns true if obj is of the same type as the IPv4 address and they have
-     * the same IP address, false otherwise.
-     * 
-     * @return true if equal and false otherwise
+     * Compares this instance with the IP address in the object {@code obj} and
+     * returns {@code true} if they are of the same type and represent the same
+     * IP address, {@code false} otherwise.
+     * 
+     * @param obj
+     *            the object to be tested for equality.
+     * @return {@code true} if the addresses are equal, {@code false} otherwise.
      */
     @Override
     public boolean equals(Object obj) {

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/Inet6Address.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/Inet6Address.java?rev=772095&r1=772094&r2=772095&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/Inet6Address.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/Inet6Address.java Wed May  6 08:33:17 2009
@@ -26,6 +26,9 @@
 import org.apache.harmony.luni.util.Inet6Util;
 import org.apache.harmony.luni.util.Msg;
 
+/**
+ * This class represents a 128 bit long IPv6 address.
+ */
 public final class Inet6Address extends InetAddress {
 
     private static final long serialVersionUID = 6880410070516793377L;
@@ -66,15 +69,15 @@
     }
 
     /**
-     * Constructs an InetAddress, representing the <code>address</code> and
-     * <code>hostName</code> and <code>scope_id</code>
+     * Constructs an {@code InetAddress} representing the {@code address} and
+     * {@code name} and {@code scope_id}.
      * 
      * @param address
-     *            network address
+     *            the network address.
      * @param name
-     *            Name associated with the address
+     *            the name associated with the address.
      * @param scope_id
-     *            The scope id for link or site local addresses
+     *            the scope id for link- or site-local addresses.
      */
     Inet6Address(byte address[], String name, int scope_id) {
         hostName = name;
@@ -86,18 +89,18 @@
     }
 
     /**
-     * Constructs an IPv6 address according to the given <code>host</code>,
-     * <code>addr</code> and <code>scope_id</code>.
+     * Constructs an IPv6 address according to the given {@code host}, {@code
+     * addr} and {@code scope_id}.
      * 
      * @param host
-     *            hostname associated with the address
+     *            the host name associated with the address.
      * @param addr
-     *            network address
+     *            the network address.
      * @param scope_id
-     *            the scope id for link or site local addresses
-     * @return an Inet6Address instance
+     *            the scope id for link- or site-local addresses.
+     * @return the Inet6Address instance representing the IP address.
      * @throws UnknownHostException
-     *             if the address is null or of invalid length
+     *             if the address is null or has an invalid length.
      */
     public static Inet6Address getByAddress(String host, byte[] addr,
             int scope_id) throws UnknownHostException {
@@ -112,21 +115,21 @@
     }
 
     /**
-     * Constructs an IPv6 address according to the given <code>host</code>,
-     * <code>addr</code> and <code>nif</code>. <code>scope_id</code> is
-     * set according to the given <code>nif</code> and the
-     * <code>addr<code> type(e.g. site local or link local).
+     * Gets an IPv6 address instance according to the given {@code host},
+     * {@code addr} and {@code nif}. {@code scope_id} is set according to the
+     * given {@code nif} and the {@code addr} type (for example site-local or
+     * link-local).
      * 
      * @param host
-     *            host name associated with the address
+     *            the hostname associated with the address.
      * @param addr
-     *            network address
+     *            the network address.
      * @param nif
-     *            the Network Interface that this address is associated with.
-     * @return an Inet6Address instance
+     *            the network interface that this address is associated with.
+     * @return the Inet6Address instance representing the IP address.
      * @throws UnknownHostException
-     *             if the address is null or of invalid length, or the
-     *             interface doesn't have a numeric scope id for the given
+     *             if the address is {@code null} or has an invalid length or
+     *             the interface doesn't have a numeric scope id for the given
      *             address type.
      */
     public static Inet6Address getByAddress(String host, byte[] addr,
@@ -167,9 +170,11 @@
     }
 
     /**
-     * Returns true if one of following cases is true: 1. both addresses are
-     * site local; 2. both addresses are link local; 3. ia is neither site local
-     * nor link local;
+     * Returns {@code true} if one of following cases applies:
+     * <p>
+     * <li>1. both addresses are site local</li>
+     * <li>2. both addresses are link local</li>
+     * <li>3. {@code ia} is neither site local nor link local</li>
      */
     private boolean compareLocalType(Inet6Address ia) {
         if (ia.isSiteLocalAddress() && isSiteLocalAddress()) {
@@ -185,13 +190,13 @@
     }
 
     /**
-     * Constructs an InetAddress, representing the <code>address</code> and
-     * <code>hostName</code> and <code>scope_id</code>
+     * Constructs an {@code InetAddress} representing the {@code address} and
+     * {@code scope_id}.
      * 
      * @param address
-     *            network address
+     *            the network address.
      * @param scope_id
-     *            The scope id for link or site local addresses
+     *            the scope id for link- or site-local addresses.
      */
     Inet6Address(byte address[], int scope_id) {
         ipaddress = address;
@@ -202,13 +207,11 @@
     }
 
     /**
-     * Answer true if the InetAddress is an IP multicast address.
+     * Returns whether this address is an IP multicast address or not. Valid
+     * IPv6 multicast addresses are binary prefixed with 11111111 or FF (hex).
      * 
-     * Valid IPv6 multicast address have the binary prefixed with 11111111 or FF
-     * (hex).
-     * 
-     * @return boolean true, if the address is in the multicast group, false
-     *         otherwise
+     * @return {@code true} if this address is in the multicast group, {@code
+     *         false} otherwise.
      */
     @Override
     public boolean isMulticastAddress() {
@@ -217,10 +220,11 @@
     }
 
     /**
-     * Answer true if the InetAddress is the unspecified address "::".
+     * Returns whether this address is a unspecified wildcard address "::" or
+     * not.
      * 
-     * @return boolean true, if the address is in the multicast group, false
-     *         otherwise
+     * @return {@code true} if this instance represents a wildcard address,
+     *         {@code false} otherwise.
      */
     @Override
     public boolean isAnyLocalAddress() {
@@ -233,11 +237,11 @@
     }
 
     /**
-     * Answer true if the InetAddress is the loopback address
-     * 
-     * The valid IPv6 loopback address is ::1
+     * Returns whether this address is the loopback address or not. The only
+     * valid IPv6 loopback address is "::1".
      * 
-     * @return boolean true if the address is the loopback, false otherwise
+     * @return {@code true} if this instance represents the loopback address,
+     *         {@code false} otherwise.
      */
     @Override
     public boolean isLoopbackAddress() {
@@ -258,11 +262,11 @@
     }
 
     /**
-     * Answer true if the InetAddress is a link-local address.
+     * Returns whether this address is a link-local address or not. A valid IPv6
+     * link-local address is prefixed with 1111111010.
      * 
-     * A valid IPv6 link-local address is prefixed with 1111111010
-     * 
-     * @return boolean true, if it is a link-local address, false otherwise
+     * @return {@code true} if this instance represents a link-local address,
+     *         {@code false} otherwise.
      */
     @Override
     public boolean isLinkLocalAddress() {
@@ -272,11 +276,11 @@
     }
 
     /**
-     * Answer true if the InetAddress is a site-local address.
-     * 
-     * A valid IPv6 site-local address is prefixed with 1111111011
+     * Returns whether this address is a site-local address or not. A valid IPv6
+     * site-local address is prefixed with 1111111011.
      * 
-     * @return boolean true, if it is a site-local address, false otherwise
+     * @return {@code true} if this instance represents a site-local address,
+     *         {@code false} otherwise.
      */
     @Override
     public boolean isSiteLocalAddress() {
@@ -286,12 +290,11 @@
     }
 
     /**
-     * Answer true if the InetAddress is a global multicast address.
+     * Returns whether this address is a global multicast address or not. A
+     * valid IPv6 global multicast address is 11111111xxxx1110 or FF0E hex.
      * 
-     * A valid IPv6 global multicast address is 11111111xxxx1110 (i.e. FF0E)
-     * 
-     * @return boolean true, if it is a global multicast address, false
-     *         otherwise
+     * @return {@code true} if this instance represents a global multicast
+     *         address, {@code false} otherwise.
      */
     @Override
     public boolean isMCGlobal() {
@@ -301,13 +304,12 @@
     }
 
     /**
-     * Answer true if the InetAddress is a node-local multicast address.
-     * 
-     * A valid IPv6 node-local multicast address is prefixed with
-     * 11111111xxxx0001
+     * Returns whether this address is a node-local multicast address or not. A
+     * valid IPv6 node-local multicast address is prefixed with
+     * 11111111xxxx0001.
      * 
-     * @return boolean true, if it is a node-local multicast address, false
-     *         otherwise
+     * @return {@code true} if this instance represents a node-local multicast
+     *         address, {@code false} otherwise.
      */
     @Override
     public boolean isMCNodeLocal() {
@@ -317,13 +319,12 @@
     }
 
     /**
-     * Answer true if the InetAddress is a link-local multicast address.
+     * Returns whether this address is a link-local multicast address or not. A
+     * valid IPv6 link-local multicast address is prefixed with
+     * 11111111xxxx0010.
      * 
-     * A valid IPv6 link-local multicast address is prefixed with
-     * 11111111xxxx0010
-     * 
-     * @return boolean true, if it is a link-local multicast address, false
-     *         otherwise
+     * @return {@code true} if this instance represents a link-local multicast
+     *         address, {@code false} otherwise.
      */
     @Override
     public boolean isMCLinkLocal() {
@@ -333,13 +334,12 @@
     }
 
     /**
-     * Answer true if the InetAddress is a site-local multicast address.
-     * 
-     * A valid IPv6 site-local multicast address is prefixed with
-     * 11111111xxxx0101
+     * Returns whether this address is a site-local multicast address or not. A
+     * valid IPv6 site-local multicast address is prefixed with
+     * 11111111xxxx0101.
      * 
-     * @return boolean true, if it is a site-local multicast address, false
-     *         otherwise
+     * @return {@code true} if this instance represents a site-local multicast
+     *         address, {@code false} otherwise.
      */
     @Override
     public boolean isMCSiteLocal() {
@@ -349,13 +349,12 @@
     }
 
     /**
-     * Answer true if the InetAddress is a org-local multicast address.
+     * Returns whether this address is a organization-local multicast address or
+     * not. A valid IPv6 org-local multicast address is prefixed with
+     * 11111111xxxx1000.
      * 
-     * A valid IPv6 org-local multicast address is prefixed with
-     * 11111111xxxx1000
-     * 
-     * @return boolean true, if it is a org-local multicast address, false
-     *         otherwise
+     * @return {@code true} if this instance represents a org-local multicast
+     *         address, {@code false} otherwise.
      */
     @Override
     public boolean isMCOrgLocal() {
@@ -364,16 +363,22 @@
         return (ipaddress[0] == -1) && (ipaddress[1] & 15) == 8;
     }
 
+    /**
+     * Gets the textual representation of this IP address.
+     * 
+     * @return the as a dotted string formatted IP address.
+     */
     @Override
     public String getHostAddress() {
         return Inet6Util.createIPAddrStringFromByteArray(ipaddress);
     }
 
     /**
-     * Returns the <code>scope id</code> of this address if it is associated
-     * with an interface. Otherwise returns zero.
+     * Gets the scope id as a number if this address is linked to an interface.
+     * Otherwise returns {@code 0}.
      * 
-     * @return the scope_id.
+     * @return the scope_id of this address or 0 when not linked with an
+     *         interface.
      */
     public int getScopeId() {
         if (scope_id_set) {
@@ -383,10 +388,10 @@
     }
 
     /**
-     * Returns the network interface if this address is instanced with a scoped
-     * network interface. Otherwise returns null.
+     * Gets the network interface if this address is instanced with a scoped
+     * network interface. Otherwise returns {@code null}.
      * 
-     * @return the scoped network interface.
+     * @return the scoped network interface of this address.
      */
     public NetworkInterface getScopedInterface() {
         if (scope_ifname_set) {
@@ -396,9 +401,9 @@
     }
 
     /**
-     * Returns the hashcode of the receiver.
+     * Gets the hashcode of the represented IP address.
      * 
-     * @return the hashcode
+     * @return the appropriate hashcode value.
      */
     @Override
     public int hashCode() {
@@ -407,12 +412,14 @@
     }
 
     /**
-     * Returns true if obj is of the same type as the IPv6 address and they have
-     * the same IP address, false otherwise. the scope id does not seem to be
-     * part of the comparison
-     * 
-     * @return String
-     * 
+     * Compares this instance with the IP address in the object {@code obj} and
+     * returns {@code true} if they are of the same type and represent the same
+     * IP address, {@code false} otherwise. The scope id does not seem to be
+     * part of the comparison.
+     * 
+     * @param obj
+     *            the object to be tested for equality.
+     * @return {@code true} if the addresses are equal, {@code false} otherwise.
      */
     @Override
     public boolean equals(Object obj) {
@@ -420,8 +427,12 @@
     }
 
     /**
-     * An IPv4 compatible address is prefixed with 96 bits of 0's. The last
-     * 32-bits are varied corresponding with the 32-bit IPv4 address space.
+     * Returns whether this address is IPv4 compatible or not. An IPv4
+     * compatible address is prefixed with 96 bits of 0's. The last 32-bits are
+     * varied corresponding with the 32-bit IPv4 address space.
+     * 
+     * @return {@code true} if this instance represents an IPv4 compatible
+     *         address, {@code false} otherwise.
      */
     public boolean isIPv4CompatibleAddress() {
         for (int i = 0; i < 12; i++) {
@@ -468,10 +479,10 @@
     }
 
     /**
-     * Answers a string containing a concise, human-readable description of the
-     * address.
+     * Returns a string containing a concise, human-readable description of this
+     * IP address.
      * 
-     * @return String the description, as host/address
+     * @return the description, as host/address.
      */
     @Override
     public String toString() {

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/InetAddress.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/InetAddress.java?rev=772095&r1=772094&r2=772095&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/InetAddress.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/InetAddress.java Wed May  6 08:33:17 2009
@@ -37,9 +37,10 @@
 import org.apache.harmony.luni.util.PriviAction;
 
 /**
- * The Internet Protocol (IP) address class. This class encapsulates an IP
- * address and provides name and reverse name resolution functions. The address
- * is stored in network order, but as a signed (rather than unsigned) integer.
+ * The Internet Protocol (IP) address representation class. This class
+ * encapsulates an IP address and provides name and reverse name resolution
+ * functions. The address is stored in network order, but as a signed (rather
+ * than unsigned) integer.
  */
 public class InetAddress extends Object implements Serializable {
 
@@ -88,11 +89,11 @@
     }
 
     /**
-     * Constructs an InetAddress, representing the <code>address</code> and
-     * <code>hostName</code>.
-     * 
+     * Constructs an {@code InetAddress}, representing the {@code address} and
+     * {@code hostName}.
+     *
      * @param address
-     *            network address
+     *            the network address.
      */
     InetAddress(byte[] address) {
         super();
@@ -100,11 +101,11 @@
     }
 
     /**
-     * Constructs an InetAddress, representing the <code>address</code> and
-     * <code>hostName</code>.
+     * Constructs an {@code InetAddress}, representing the {@code address} and
+     * {@code hostName}.
      * 
      * @param address
-     *            network address
+     *            the network address.
      */
     InetAddress(byte[] address, String hostName) {
         super();
@@ -117,11 +118,13 @@
     }
 
     /**
-     * Compares this <code>InetAddress</code> against the specified object.
+     * Compares this {@code InetAddress} instance against the specified address
+     * in {@code obj}. Two addresses are equal if their address byte arrays have
+     * the same length and if the bytes in the arrays are equal.
      * 
      * @param obj
-     *            the object to be tested for equality
-     * @return boolean true, if the objects are equal
+     *            the object to be tested for equality.
+     * @return {@code true} if both objects are equal, {@code false} otherwise.
      */
     @Override
     public boolean equals(Object obj) {
@@ -143,28 +146,29 @@
     }
 
     /**
-     * Returns the IP address of this <code>InetAddress</code> as an array.
-     * The elements are in network order (the highest order address byte is in
-     * the zero-th element).
+     * Returns the IP address represented by this {@code InetAddress} instance
+     * as a byte array. The elements are in network order (the highest order
+     * address byte is in the zeroth element).
      * 
-     * @return byte[] the address as a byte array
+     * @return the address in form of a byte array.
      */
     public byte[] getAddress() {
         return ipaddress.clone();
     }
 
     /**
-     * Answer the IP addresses of a named host. The host name may either be a
-     * machine name or a dotted string IP address. If the host name is empty or
-     * null, an UnknownHostException is thrown. If the host name is a dotted IP
-     * string, an array with the corresponding single InetAddress is returned.
+     * Gets all IP addresses associated with the given {@code host} identified
+     * by name or IP address in dot-notation. The IP address is resolved by the
+     * configured name service. If the host name is empty or {@code null} an
+     * {@code UnknownHostException} is thrown. If the host name is a dotted IP
+     * address string an array with the corresponding single {@code InetAddress}
+     * is returned.
      * 
      * @param host
-     *            the hostName to be resolved to an address
-     * 
-     * @return InetAddress[] an array of addresses for the host
+     *            the host's name or IP to be resolved to an address.
+     * @return the array of addresses associated with the specified host.
      * @throws UnknownHostException
-     *             if the address lookup fails
+     *             if the address lookup fails.
      */
     public static InetAddress[] getAllByName(String host)
             throws UnknownHostException {
@@ -231,16 +235,17 @@
     }
 
     /**
-     * Answers the address of a host, given a host string name. The host string
-     * may be either a machine name or a dotted string IP address. If the
-     * latter, the hostName field will be determined upon demand.
+     * Returns the address of a host according to the given host string name
+     * {@code host}. The host string may be either a machine name or a dotted
+     * string IP address. If the latter, the {@code hostName} field is
+     * determined upon demand. {@code host} can be {@code null} which means that
+     * an address of the loopback interface is returned.
      * 
      * @param host
-     *            the hostName to be resolved to an address
-     * @return InetAddress the InetAddress representing the host
-     * 
+     *            the hostName to be resolved to an address or {@code null}.
+     * @return the {@code InetAddress} instance representing the host.
      * @throws UnknownHostException
-     *             if the address lookup fails
+     *             if the address lookup fails.
      */
     public static InetAddress getByName(String host)
             throws UnknownHostException {
@@ -263,18 +268,21 @@
     }
 
     /**
-     * Answer the dotted string IP address representing this address.
+     * Gets the textual representation of this IP address.
      * 
-     * @return String the corresponding dotted string IP address
+     * @return the textual representation of this host address in form of a
+     *         dotted string.
      */
     public String getHostAddress() {
         return inetNtoaImpl(bytesToInt(ipaddress, 0));
     }
 
     /**
-     * Answer the host name.
+     * Gets the host name of this IP address. If the IP address could not be
+     * resolved, the textual representation in a dotted-quad-notation is
+     * returned.
      * 
-     * @return String the corresponding string name
+     * @return the corresponding string name of this IP address.
      */
     public String getHostName() {
         try {
@@ -309,9 +317,12 @@
     }
 
     /**
-     * Answers canonical name for the host associated with the internet address
+     * Gets the fully qualified domain name for the host associated with this IP
+     * address. If a security manager is set, it is checked if the method caller
+     * is allowed to get the hostname. Otherwise, the textual representation in
+     * a dotted-quad-notation is returned.
      * 
-     * @return String string containing the host name
+     * @return the fully qualified domain name of this IP address.
      */
     public String getCanonicalHostName() {
         String canonicalName;
@@ -340,12 +351,13 @@
     }
 
     /**
-     * Answer the local host, if allowed by the security policy. Otherwise,
-     * answer the loopback address which allows this machine to be contacted.
-     * 
-     * @return InetAddress the InetAddress representing the local host
+     * Gets the local host address if the security policy allows this.
+     * Otherwise, gets the loopback address which allows this machine to be
+     * contacted.
+     *
+     * @return the {@code InetAddress} representing the local host.
      * @throws UnknownHostException
-     *             if the address lookup fails
+     *             if the address lookup fails.
      */
     public static InetAddress getLocalHost() throws UnknownHostException {
         String host = getHostNameImpl();
@@ -361,9 +373,9 @@
     }
 
     /**
-     * Answer a hashcode for this IP address.
+     * Gets the hashcode of the represented IP address.
      * 
-     * @return int the hashcode
+     * @return the appropriate hashcode value.
      */
     @Override
     public int hashCode() {
@@ -371,9 +383,10 @@
     }
 
     /**
-     * Answer true if the InetAddress is an IP multicast address.
+     * Returns whether this address is an IP multicast address or not.
      * 
-     * @return boolean true, if the address is in the multicast group
+     * @return {@code true} if this address is in the multicast group, {@code
+     *         false} otherwise.
      */
     public boolean isMulticastAddress() {
         return ((ipaddress[0] & 255) >>> 4) == 0xE;
@@ -447,9 +460,9 @@
      * Query the IP stack for the host address. The host is in address form.
      * 
      * @param addr
-     *            the host address to lookup
+     *            the host address to lookup.
      * @throws UnknownHostException
-     *             if an error occurs during lookup
+     *             if an error occurs during lookup.
      */
     static native InetAddress getHostByAddrImpl(byte[] addr)
             throws UnknownHostException;
@@ -460,7 +473,7 @@
     }
 
     /**
-     * Convert a string containing an Ipv4 Internet Protocol dotted address into
+     * Convert a string containing an IPv4 Internet Protocol dotted address into
      * a binary address. Note, the special case of '255.255.255.255' throws an
      * exception, so this value should not be used as an argument. See also
      * inetAddr(String).
@@ -481,7 +494,6 @@
      * @param preferIPv6Addresses
      *            address preference if underlying platform is V4/V6
      * @return InetAddress the host address
-     * 
      * @throws UnknownHostException
      *             if an error occurs during lookup
      */
@@ -489,9 +501,9 @@
             boolean preferIPv6Address) throws UnknownHostException;
 
     /**
-     * Query the IP stack for the host machine name.
+     * Gets the host name of the system.
      * 
-     * @return String the host machine name
+     * @return String the system hostname
      */
     static native String getHostNameImpl();
 
@@ -506,10 +518,10 @@
     }
 
     /**
-     * Answers a string containing a concise, human-readable description of the
-     * address.
+     * Returns a string containing a concise, human-readable description of this
+     * IP address.
      * 
-     * @return String the description, as host/address
+     * @return the description, as host/address.
      */
     @Override
     public String toString() {
@@ -603,7 +615,7 @@
     }
 
     /**
-     * Answer true if the string is a host name, false if it is an IP Address.
+     * Returns true if the string is a host name, false if it is an IP Address.
      */
     private static boolean isHostName(String value) {
         return !(Inet6Util.isValidIPV4Address(value) || Inet6Util
@@ -611,163 +623,186 @@
     }
 
     /**
-     * Answer true if the address is a loop back address. Valid IPv4 loopback
-     * addresses are 127.d.d.d Valid IPv6 loopback address is ::1
+     * Returns whether this address is a loopback address or not. This
+     * implementation returns always {@code false}. Valid IPv4 loopback
+     * addresses are 127.d.d.d The only valid IPv6 loopback address is ::1.
      * 
-     * @return boolean
+     * @return {@code true} if this instance represents a loopback address,
+     *         {@code false} otherwise.
      */
     public boolean isLoopbackAddress() {
         return false;
     }
 
     /**
-     * Answers true if the address is a link local address.
-     * 
-     * Valid IPv6 link local addresses are FE80::0 through to
-     * FEBF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF
-     * 
-     * There are no valid IPv4 link local addresses.
-     * 
-     * @return boolean
+     * Returns whether this address is a link-local address or not. This
+     * implementation returns always {@code false}.
+     * <p>
+     * Valid IPv6 link-local addresses are FE80::0 through to
+     * FEBF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF.
+     * <p>
+     * There are no valid IPv4 link-local addresses.
+     *
+     * @return {@code true} if this instance represents a link-local address,
+     *         {@code false} otherwise.
      */
     public boolean isLinkLocalAddress() {
         return false;
     }
 
     /**
-     * Answers true if the address is a site local address.
+     * Returns whether this address is a site-local address or not. This
+     * implementation returns always {@code false}.
+     * <p>
+     * Valid IPv6 site-local addresses are FEC0::0 through to
+     * FEFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF.
+     * <p>
+     * There are no valid IPv4 site-local addresses.
      * 
-     * Valid IPv6 link local addresses are FEC0::0 through to
-     * FEFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF
-     * 
-     * There are no valid IPv4 site local addresses.
-     * 
-     * @return boolean
+     * @return {@code true} if this instance represents a site-local address,
+     *         {@code false} otherwise.
      */
     public boolean isSiteLocalAddress() {
         return false;
     }
 
     /**
-     * Answers true if the address is a global multicast address.
-     * 
-     * Valid IPv6 link global multicast addresses are FFxE:/112 where x is a set
+     * Returns whether this address is a global multicast address or not. This
+     * implementation returns always {@code false}.
+     * <p>
+     * Valid IPv6 link-global multicast addresses are FFxE:/112 where x is a set
      * of flags, and the additional 112 bits make up the global multicast
-     * address space
-     * 
+     * address space.
+     * <p>
      * Valid IPv4 global multicast addresses are between: 224.0.1.0 to
-     * 238.255.255.255
-     * 
-     * @return boolean
+     * 238.255.255.255.
+     *
+     * @return {@code true} if this instance represents a global multicast
+     *         address, {@code false} otherwise.
      */
     public boolean isMCGlobal() {
         return false;
     }
 
     /**
-     * Answers true if the address is a node local multicast address.
-     * 
-     * Valid IPv6 node local multicast addresses are FFx1:/112 where x is a set
-     * of flags, and the additional 112 bits make up the node local multicast
-     * address space
-     * 
-     * There are no valid IPv4 node local multicast addresses.
-     * 
-     * @return boolean
+     * Returns whether this address is a node-local multicast address or not.
+     * This implementation returns always {@code false}.
+     * <p>
+     * Valid IPv6 node-local multicast addresses are FFx1:/112 where x is a set
+     * of flags, and the additional 112 bits make up the node-local multicast
+     * address space.
+     * <p>
+     * There are no valid IPv4 node-local multicast addresses.
+     *
+     * @return {@code true} if this instance represents a node-local multicast
+     *         address, {@code false} otherwise.
      */
     public boolean isMCNodeLocal() {
         return false;
     }
 
     /**
-     * Answers true if the address is a link local multicast address.
-     * 
-     * Valid IPv6 link local multicast addresses are FFx2:/112 where x is a set
-     * of flags, and the additional 112 bits make up the node local multicast
-     * address space
-     * 
+     * Returns whether this address is a link-local multicast address or not.
+     * This implementation returns always {@code false}.
+     * <p>
+     * Valid IPv6 link-local multicast addresses are FFx2:/112 where x is a set
+     * of flags, and the additional 112 bits make up the link-local multicast
+     * address space.
+     * <p>
      * Valid IPv4 link-local addresses are between: 224.0.0.0 to 224.0.0.255
-     * 
-     * @return boolean
+     *
+     * @return {@code true} if this instance represents a link-local multicast
+     *         address, {@code false} otherwise.
      */
     public boolean isMCLinkLocal() {
         return false;
     }
 
     /**
-     * Answers true if the address is a site local multicast address.
-     * 
-     * Valid IPv6 site local multicast addresses are FFx5:/112 where x is a set
-     * of flags, and the additional 112 bits make up the node local multicast
-     * address space
-     * 
+     * Returns whether this address is a site-local multicast address or not.
+     * This implementation returns always {@code false}.
+     * <p>
+     * Valid IPv6 site-local multicast addresses are FFx5:/112 where x is a set
+     * of flags, and the additional 112 bits make up the site-local multicast
+     * address space.
+     * <p>
      * Valid IPv4 site-local addresses are between: 239.252.0.0 to
      * 239.255.255.255
-     * 
-     * @return boolean
+     *
+     * @return {@code true} if this instance represents a site-local multicast
+     *         address, {@code false} otherwise.
      */
     public boolean isMCSiteLocal() {
         return false;
     }
 
     /**
-     * Answers true if the address is a organization local multicast address.
-     * 
-     * Valid IPv6 organization local multicast addresses are FFx8:/112 where x
-     * is a set of flags, and the additional 112 bits make up the node local
-     * multicast address space
-     * 
+     * Returns whether this address is a organization-local multicast address or
+     * not. This implementation returns always {@code false}.
+     * <p>
+     * Valid IPv6 organization-local multicast addresses are FFx8:/112 where x
+     * is a set of flags, and the additional 112 bits make up the
+     * organization-local multicast address space.
+     * <p>
      * Valid IPv4 organization-local addresses are between: 239.192.0.0 to
      * 239.251.255.255
-     * 
-     * @return boolean
+     *
+     * @return {@code true} if this instance represents a organization-local
+     *         multicast address, {@code false} otherwise.
      */
     public boolean isMCOrgLocal() {
         return false;
     }
 
     /**
-     * Method isAnyLocalAddress.
+     * Returns whether this is a wildcard address or not. This implementation
+     * returns always {@code false}.
      * 
-     * @return boolean
+     * @return {@code true} if this instance represents a wildcard address,
+     *         {@code false} otherwise.
      */
     public boolean isAnyLocalAddress() {
         return false;
     }
 
     /**
-     * Tries to see if the InetAddress is reachable. This method first tries to
-     * use ICMP(ICMP ECHO REQUEST). When first step fails, the TCP connection on
-     * port 7 (Echo) shall be lauched.
+     * Tries to reach this {@code InetAddress}. This method first tries to use
+     * ICMP <i>(ICMP ECHO REQUEST)</i>. When first step fails, a TCP connection
+     * on port 7 (Echo) of the remote host is established.
      * 
      * @param timeout
-     *            timeout in milliseconds
-     * @return true if address is reachable
+     *            timeout in milliseconds before the test fails if no connection
+     *            could be established.
+     * @return {@code true} if this address is reachable, {@code false}
+     *         otherwise.
      * @throws IOException
-     *             if I/O operation meets error
+     *             if an error occurs during an I/O operation.
      * @throws IllegalArgumentException
-     *             if timeout is less than zero
+     *             if timeout is less than zero.
      */
     public boolean isReachable(int timeout) throws IOException {
         return isReachable(null, 0, timeout);
     }
 
     /**
-     * Tries to see if the InetAddress is reachable. This method first tries to
-     * use ICMP(ICMP ECHO REQUEST). When first step fails, the TCP connection on
-     * port 7 (Echo) shall be lauched.
+     * Tries to reach this {@code InetAddress}. This method first tries to use
+     * ICMP <i>(ICMP ECHO REQUEST)</i>. When first step fails, a TCP connection
+     * on port 7 (Echo) of the remote host is established.
      * 
      * @param netif
-     *            the network interface through which to connect
+     *            the network interface on which to connection should be
+     *            established.
      * @param ttl
-     *            max hops to live
+     *            the maximum count of hops (time-to-live).
      * @param timeout
-     *            timeout in milliseconds
-     * @return true if address is reachable
+     *            timeout in milliseconds before the test fails if no connection
+     *            could be established.
+     * @return {@code true} if this address is reachable, {@code false}
+     *         otherwise.
      * @throws IOException
-     *             if I/O operation meets error
+     *             if an error occurs during an I/O operation.
      * @throws IllegalArgumentException
-     *             if ttl or timeout is less than zero
+     *             if ttl or timeout is less than zero.
      */
     public boolean isReachable(NetworkInterface netif, final int ttl,
             final int timeout) throws IOException {
@@ -934,19 +969,20 @@
     }
 
     /**
-     * Answers the InetAddress corresponding to the array of bytes. In the case
-     * of an IPv4 address there must be exactly 4 bytes and for IPv6 exactly 16
-     * bytes. If not, an UnknownHostException is thrown.
-     * 
+     * Returns the {@code InetAddress} corresponding to the array of bytes. In
+     * the case of an IPv4 address there must be exactly 4 bytes and for IPv6
+     * exactly 16 bytes. If not, an {@code UnknownHostException} is thrown.
+     * <p>
      * The IP address is not validated by a name service.
-     * 
-     * The high order byte is <code>ipAddress[0]</code>.
-     * 
+     * <p>
+     * The high order byte is {@code ipAddress[0]}.
+     *
      * @param ipAddress
-     *            either a 4 (IPv4) or 16 (IPv6) byte array
-     * @return the InetAddress
-     * 
+     *            is either a 4 (IPv4) or 16 (IPv6) byte long array.
+     * @return an {@code InetAddress} instance representing the given IP address
+     *         {@code ipAddress}.
      * @throws UnknownHostException
+     *             if the given byte array has no valid length.
      */
     public static InetAddress getByAddress(byte[] ipAddress)
             throws UnknownHostException {
@@ -956,21 +992,18 @@
     }
 
     /**
-     * Answers the InetAddress corresponding to the array of bytes. In the case
-     * of an IPv4 address there must be exactly 4 bytes and for IPv6 exactly 16
-     * bytes. If not, an UnknownHostException is thrown.
-     * 
-     * The IP address is not validated by a name service.
-     * 
-     * The high order byte is <code>ipAddress[0]</code>.
+     * Returns the {@code InetAddress} corresponding to the array of bytes. In
+     * the case of an IPv4 address there must be exactly 4 bytes and for IPv6
+     * exactly 16 bytes. If not, an {@code UnknownHostException} is thrown. The
+     * IP address is not validated by a name service. The high order byte is
+     * {@code ipAddress[0]}.
      * 
      * @param ipAddress
-     *            either a 4 (IPv4) or 16 (IPv6) byte array
+     *            either a 4 (IPv4) or 16 (IPv6) byte array.
      * @param scope_id
      *            the scope id for an IPV6 scoped address. If not a scoped
-     *            address just pass in 0
+     *            address just pass in 0.
      * @return the InetAddress
-     * 
      * @throws UnknownHostException
      */
     static InetAddress getByAddress(byte[] ipAddress, int scope_id)
@@ -1021,25 +1054,26 @@
     }
 
     /**
-     * Answers the InetAddress corresponding to the array of bytes, and the
-     * given hostname. In the case of an IPv4 address there must be exactly 4
-     * bytes and for IPv6 exactly 16 bytes. If not, an UnknownHostException is
-     * thrown.
-     * 
+     * Returns the {@code InetAddress} corresponding to the array of bytes, and
+     * the given hostname. In the case of an IPv4 address there must be exactly
+     * 4 bytes and for IPv6 exactly 16 bytes. If not, an {@code
+     * UnknownHostException} will be thrown.
+     * <p>
      * The host name and IP address are not validated.
-     * 
+     * <p>
      * The hostname either be a machine alias or a valid IPv6 or IPv4 address
      * format.
-     * 
-     * The high order byte is <code>ipAddress[0]</code>.
-     * 
+     * <p>
+     * The high order byte is {@code ipAddress[0]}.
+     *
      * @param hostName
-     *            string representation of hostname or ip address
+     *            the string representation of hostname or IP address.
      * @param ipAddress
-     *            either a 4 (IPv4) or 16 (IPv6) byte array
-     * @return the InetAddress
-     * 
+     *            either a 4 (IPv4) or 16 (IPv6) byte long array.
+     * @return an {@code InetAddress} instance representing the given IP address
+     *         and hostname.
      * @throws UnknownHostException
+     *             if the given byte array has no valid length.
      */
     public static InetAddress getByAddress(String hostName, byte[] ipAddress)
             throws UnknownHostException {
@@ -1049,27 +1083,21 @@
     }
 
     /**
-     * Answers the InetAddress corresponding to the array of bytes, and the
-     * given hostname. In the case of an IPv4 address there must be exactly 4
-     * bytes and for IPv6 exactly 16 bytes. If not, an UnknownHostException is
-     * thrown.
-     * 
-     * The host name and IP address are not validated.
-     * 
-     * The hostname either be a machine alias or a valid IPv6 or IPv4 address
-     * format.
-     * 
-     * The high order byte is <code>ipAddress[0]</code>.
+     * Returns the {@code InetAddress} corresponding to the array of bytes, and
+     * the given hostname. In the case of an IPv4 address there must be exactly
+     * 4 bytes and for IPv6 exactly 16 bytes. If not, an {@code
+     * UnknownHostException} is thrown. The host name and IP address are not
+     * validated. The hostname either be a machine alias or a valid IPv6 or IPv4
+     * address format. The high order byte is {@code ipAddress[0]}.
      * 
      * @param hostName
-     *            string representation of hostname or IP address
+     *            string representation of hostname or IP address.
      * @param ipAddress
-     *            either a 4 (IPv4) or 16 (IPv6) byte array
+     *            either a 4 (IPv4) or 16 (IPv6) byte array.
      * @param scope_id
      *            the scope id for a scoped address. If not a scoped address
-     *            just pass in 0
+     *            just pass in 0.
      * @return the InetAddress
-     * 
      * @throws UnknownHostException
      */
     static InetAddress getByAddressInternal(String hostName, byte[] ipAddress,
@@ -1140,8 +1168,8 @@
     }
 
     /**
-     * Creates an InetAddress based on an ipAddressString. No error handling is
-     * performed here.
+     * Creates an InetAddress based on the {@code ipAddressString}. No error
+     * handling is performed here.
      */
     static InetAddress createHostNameFromIPAddress(String ipAddressString)
             throws UnknownHostException {



Mime
View raw message