update API docs for HTTP client and server-related classes

sdk/lib/io/socket.dart

Index: sdk/lib/io/socket.dart
diff --git a/sdk/lib/io/socket.dart b/sdk/lib/io/socket.dart
index f8d854382b3b41b8d3308301a46fb2a193047c16..b1e5be77eb44703edbc16661c1da61c9bf270376 100644
--- a/sdk/lib/io/socket.dart
+++ b/sdk/lib/io/socket.dart
@@ -41,10 +41,14 @@ class InternetAddressType {
 
 
 /**
- * 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
+ * bind.
  */
 abstract class InternetAddress {
   /**