Create a first-cut for a README for http package

pkg/http/README.md

Index: pkg/http/README.md
diff --git a/pkg/http/README.md b/pkg/http/README.md
new file mode 100644
index 0000000000000000000000000000000000000000..cb87019be62ecda43a2f750ca532758ebb106ba8
--- /dev/null
+++ b/pkg/http/README.md
@@ -0,0 +1,93 @@
+# An easy-to-use HTTP client.

[Bob Nystrom, 2013/11/26 23:06:38]

Have you looked at the main library comment in http.dart? You can probably just
steal this all from that.

[sethladd, 2013/11/26 23:11:00]

Done.

+
+This package contains a set of high-level functions and classes that
+make it easy to consume HTTP resources.

[Bob Nystrom, 2013/11/26 23:06:38]

Nit, but can you word wrap these at 80 (or 79) columns?

[sethladd, 2013/11/26 23:11:00]

Looks wrapped to me? Was it this line?

[Bob Nystrom, 2013/11/26 23:18:00]

I should have been clearer. :) It looks like this line and some of the later
ones are wrapped at *less* than 79/80. Do you mind filling the whole line?

[sethladd, 2013/11/26 23:42:09]

Done.

+
+**NOTE:** This package only works for
+server-side or command-line Dart applications.

[Bob Nystrom, 2013/11/26 23:06:38]

It might help to mention that this uses "dart:io".

[sethladd, 2013/11/26 23:11:00]

I added a mention of dart:io

+
+## Installing
+
+See the [http package on pub][hosted] for installation instructions.
+
+## Reading text from a resource
+
+Use the `read()` function to easily GET an HTTP or HTTPS resource.
+The returned future completes with a String of the response body,
+or completes with an error.
+
+    import 'package:http/http.dart' as http;
+
+    void main() {
+      http.read('https://www.example.com/').then((String contents) {

[Bob Nystrom, 2013/11/26 23:06:38]

Ditch the type annotation on the lambda, here and below. I'd probably remove the
"void" from main too.

Err, I'm conflicted here. I get that it helps readers know what type is passed
to the lambda, but I hate to encourage people to actually annotate them. I think
I'd leave it off since the API docs include the actual type signature.

[sethladd, 2013/11/26 23:11:00]

I have to respectfully disagree. Without the type annotations in the lambdas,
I'm left wondering what contents is. The purpose of this sample is to be
documentation.

+        print(contents);
+      });
+    }
+
+## Reading bytes from a resource
+
+Use the `readBytes()` function to GET a list of bytes from an HTTP or HTTPS
+resource.
+
+    import 'package:http/http.dart' as http;
+
+    void main() {
+      http.read('https://www.example.com/binary').then((Uint8List bytes) {
+        print(contents.length);
+      });
+    }
+
+## Streaming bytes from a resource
+
+Create a new `Client` to stream the bytes from a resource.

[Bob Nystrom, 2013/11/26 23:06:38]

You might want to explain why they are creating a client here and not above.

[sethladd, 2013/11/26 23:11:00]

I assume because there's no top-level convenience method to get a streaming
response? Can you recommend something here that might be more insightful?

[Bob Nystrom, 2013/11/26 23:18:00]

That's a Nathan question. :)

+
+    import 'package:http/http.dart';
+
+    main() {
+      var client = new Client();
+
+      client.send(new Request('GET', Uri.parse('http://www.google.com/')))
+      .then((StreamedResponse resp) {
+        // After the headers have been received.
+        resp.stream.listen((List<int> bytes) {
+          print('Received ${bytes.length} bytes');
+        });
+      });
+    }
+
+## Posting to a resource
+
+Use the `post()` function to easily POST a body to an HTTP or HTTPS resource.
+
+     import 'package:http/http.dart' as http;
+
+     var url = "http://example.com/whatsit/create";
+     http.post(url, body: {"name": "doodle", "color": "blue"})
+         .then((http.Response response) {
+       print("Response status: ${response.statusCode}");
+       print("Response body: ${response.body}");
+     });
+
+     http.read("http://example.com/foobar.txt").then(print);
+
+## HTTP methods
+
+There are top-level functions for each of the main HTTP methods. Each
+returns a `Future<Response>`.
+
+* `get()`
+* `post()`
+* `delete()`
+* `put()`
+* `head()`
+
+## API docs
+
+Coming soon.
+
+## Filing issues
+
+Please file issues for the http package at [http://dartbug.com/new][bugs].
+
+[hosted]: https://pub.dartlang.org/packages/http
+[bugs]: http://dartbug.com/new