update API docs for HTTP client and server-related classes

sdk/lib/io/socket.dart

 // Copyright (c) 2013, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
 part of dart.io;
 
 
 /**
  * [InternetAddressType] is the type an [InternetAddress]. Currently,
  * IP version 4 (IPv4) and IP version 6 (IPv6) are supported.
@@ skipping 23 matching lines @@
       case 1: return "IP_V6";
       default: throw new ArgumentError("Invalid InternetAddress");
     }
   }
 
   String toString() => "InternetAddressType: $name";
 }
 
 
 /**
- * The [InternetAddress] is an object reflecting either a remote or a
- * local address. When combined with a port number, this represents a
- * endpoint that a socket can connect to or a listening socket can
- * bind to.
+ * A remote or local internet address.

[Søren Gjesse, 2014/03/25 10:27:26]

Maybe change this to something like this

This object holds an internet address. If this internet address is the result of
a DNS lookup the address also hold the hostname used to make the lookup.

[mem, 2014/03/25 17:30:49]

We need to use noun phrases for the short one line descriptions.

On 2014/03/25 10:27:26, Søren Gjesse wrote:

+ *
+ * An Internet address combined with a port number represents an
+ * endpoint to which a socket can connect or a listening socket can
+ * bind.
  */
 abstract class InternetAddress {
   /**
    * IP version 4 loopback address. Use this address when listening on
    * or connecting to the loopback adapter using IP version 4 (IPv4).
    */
   external static InternetAddress get LOOPBACK_IP_V4;
 
   /**
    * IP version 6 loopback address. Use this address when listening on
@@ skipping 613 matching lines @@
     }
     if (address != null) {
       sb.write(", address = ${address.host}");
     }
     if (port != null) {
       sb.write(", port = $port");
     }
     return sb.toString();
   }
 }