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..56b6959e5f42fac1359600d5f887ebfb45e91a39
--- /dev/null
+++ b/pkg/http/README.md
@@ -0,0 +1,94 @@
+# A composable, Future-based library for making HTTP requests.

[nweiz, 2013/11/27 01:51:39]

This shouldn't all be part of an h1.

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

[nweiz, 2013/11/27 01:51:39]

"consume HTTP resources" sounds stilted to me. Also, this doesn't just consume;
it can also make modifying requests like POST and DELETE.

+
+**NOTE:** This package only works for

[nweiz, 2013/11/27 01:51:39]

"only works" -> "currently only works"

As soon as it's feasible I plan to add support for XHRs.

+server-side or command-line Dart applications. In other words, if the app
+imports `dart:io`, it can use this package.

[nweiz, 2013/11/27 01:51:39]

Fix the word-wrapping in this paragraph.

+
+## Installing
+
+See the [http package on pub][hosted] for installation instructions.

[nweiz, 2013/11/27 01:51:39]

Since pub is widely-known now, installation instructions are no longer
necessary.

+
+## Reading text from a resource

[nweiz, 2013/11/27 01:51:39]

I think using REST-style "resource" terminology is going to be more confusing
than it's worth. This library is designed as an HTTP client library, not a REST
library. It doesn't have any notion of resources, and I think assuming the
reader does will make this more confusing.

+
+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) {

[nweiz, 2013/11/27 01:51:39]

Don't include type annotations for closure parameters.

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

[nweiz, 2013/11/27 01:51:39]

I don't think this is distinct enough from the previous example to warrant being
called out on its own.

+
+## Streaming bytes from a resource

[nweiz, 2013/11/27 01:51:39]

Streaming isn't a common use-case; certainly not more common than other use
cases that aren't covered here.

+
+Create a new `Client` to stream the bytes from a resource.
+
+    import 'package:http/http.dart';

[nweiz, 2013/11/27 01:51:39]

http is intended to be imported with a prefix.

+
+    main() {
+      var client = new Client();
+
+      client.send(new Request('GET', Uri.parse('http://www.google.com/')))
+      .then((StreamedResponse resp) {

[nweiz, 2013/11/27 01:51:39]

Indent this line +4 spaces.

+        // 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.

[nweiz, 2013/11/27 01:51:39]

The docs are now available at http://test.dartdoc-next.appspot.com/#http/http.

+
+## 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