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..d309515f644076dd5b16513f9d8260ab73d9692f 100644
--- a/sdk/lib/io/socket.dart
+++ b/sdk/lib/io/socket.dart
@@ -41,10 +41,11 @@ 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.
+ * 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 {
   /**