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.
+ * An internet address.
+ *
+ * This object holds an internet address. If this internet address
+ * is the result of a DNS lookup, the address also holds the hostname
+ * used to make the lookup.
+ * An Internet address combined with a port number represents an
+ * endpoint to which a socket can connect or a listening socket can

[Anders Johnsen, 2014/03/27 12:29:36]

We call the listening socket a server socket in the APIs.

+ * 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();
   }
 }