Documentation cleanup (#132)

Author: donny-dont

lib/browser_client.dart

@@ -19,11 +19,10 @@ import 'src/response.dart';
 /// A `dart:html`-based HTTP client that runs in the browser and is backed by
 /// XMLHttpRequests.
 ///
-/// This client inherits some of the limitations of XMLHttpRequest. It ignores
-/// the [BaseRequest.contentLength], [BaseRequest.persistentConnection],
-/// [BaseRequest.followRedirects], and [BaseRequest.maxRedirects] fields. It is
-/// also unable to stream requests or responses; a request will only be sent and
-/// a response will only be returned once all the data is available.
+/// This client inherits some of the limitations of XMLHttpRequest. It is
+/// unable to directly set some headers, such as `content-length`. It is also
+/// unable to stream requests or responses; a request will only be sent and a
+/// response will only be returned once all the data is available.
 class BrowserClient extends BaseClient {
   /// The currently active XHRs.
   ///
@@ -33,7 +32,6 @@ class BrowserClient extends BaseClient {
   /// Creates a new HTTP client.
   BrowserClient();
 
-  /// Sends an HTTP request and asynchronously returns the response.
   Future<Response> send(Request request) async {
     var bytes = await collectBytes(request.read());
     var xhr = new HttpRequest();
@@ -90,9 +88,6 @@ class BrowserClient extends BaseClient {
     request.open(method, url, async: asynch, user: user, password: password);
   }
 
-  /// Closes the client.
-  ///
-  /// This terminates all active requests.
   void close() {
     for (var xhr in _xhrs) {
       xhr.abort();

lib/http.dart

@@ -28,7 +28,9 @@ export 'src/response.dart';
 /// the request is complete. If you're planning on making multiple requests to
 /// the same server, you should use a single [Client] for all of those requests.
 ///
-/// For more fine-grained control over the request, use [Request] instead.
+/// This automatically initializes a new [Client] and closes that client once
+/// the request is complete. If you're planning on making multiple requests to
+/// the same server, you should use a single [Client] for all of those requests.
 Future<Response> head(url, {Map<String, String> headers}) =>
     _withClient((client) => client.head(url, headers: headers));
 
@@ -39,7 +41,9 @@ Future<Response> head(url, {Map<String, String> headers}) =>
 /// the request is complete. If you're planning on making multiple requests to
 /// the same server, you should use a single [Client] for all of those requests.
 ///
-/// For more fine-grained control over the request, use [Request] instead.
+/// This automatically initializes a new [Client] and closes that client once
+/// the request is complete. If you're planning on making multiple requests to
+/// the same server, you should use a single [Client] for all of those requests.
 Future<Response> get(url, {Map<String, String> headers}) =>
     _withClient((client) => client.get(url, headers: headers));
 
@@ -60,8 +64,9 @@ Future<Response> get(url, {Map<String, String> headers}) =>
 ///
 /// [encoding] defaults to [UTF8].
 ///
-/// For more fine-grained control over the request, use [Request] or
-/// [StreamedRequest] instead.
+/// This automatically initializes a new [Client] and closes that client once
+/// the request is complete. If you're planning on making multiple requests to
+/// the same server, you should use a single [Client] for all of those requests.
 Future<Response> post(url, body,
         {Map<String, String> headers, Encoding encoding}) =>
     _withClient((client) =>
@@ -84,8 +89,9 @@ Future<Response> post(url, body,
 ///
 /// [encoding] defaults to [UTF8].
 ///
-/// For more fine-grained control over the request, use [Request] or
-/// [StreamedRequest] instead.
+/// This automatically initializes a new [Client] and closes that client once
+/// the request is complete. If you're planning on making multiple requests to
+/// the same server, you should use a single [Client] for all of those requests.
 Future<Response> put(url, body,
         {Map<String, String> headers, Encoding encoding}) =>
     _withClient((client) =>
@@ -108,8 +114,9 @@ Future<Response> put(url, body,
 ///
 /// [encoding] defaults to [UTF8].
 ///
-/// For more fine-grained control over the request, use [Request] or
-/// [StreamedRequest] instead.
+/// This automatically initializes a new [Client] and closes that client once
+/// the request is complete. If you're planning on making multiple requests to
+/// the same server, you should use a single [Client] for all of those requests.
 Future<Response> patch(url, body,
         {Map<String, String> headers, Encoding encoding}) =>
     _withClient((client) =>
@@ -121,8 +128,6 @@ Future<Response> patch(url, body,
 /// This automatically initializes a new [Client] and closes that client once
 /// the request is complete. If you're planning on making multiple requests to
 /// the same server, you should use a single [Client] for all of those requests.
-///
-/// For more fine-grained control over the request, use [Request] instead.
 Future<Response> delete(url, {Map<String, String> headers}) =>
     _withClient((client) => client.delete(url, headers: headers));
 
@@ -136,9 +141,6 @@ Future<Response> delete(url, {Map<String, String> headers}) =>
 /// This automatically initializes a new [Client] and closes that client once
 /// the request is complete. If you're planning on making multiple requests to
 /// the same server, you should use a single [Client] for all of those requests.
-///
-/// For more fine-grained control over the request and response, use [Request]
-/// instead.
 Future<String> read(url, {Map<String, String> headers}) =>
     _withClient((client) => client.read(url, headers: headers));
 
@@ -152,9 +154,6 @@ Future<String> read(url, {Map<String, String> headers}) =>
 /// This automatically initializes a new [Client] and closes that client once
 /// the request is complete. If you're planning on making multiple requests to
 /// the same server, you should use a single [Client] for all of those requests.
-///
-/// For more fine-grained control over the request and response, use [Request]
-/// instead.
 Future<Uint8List> readBytes(url, {Map<String, String> headers}) =>
     _withClient((client) => client.readBytes(url, headers: headers));
 

lib/src/base_client.dart

@@ -13,136 +13,46 @@ import 'exception.dart';
 import 'request.dart';
 import 'response.dart';
 
-/// The abstract base class for an HTTP client. This is a mixin-style class;
-/// subclasses only need to implement [send] and maybe [close], and then they
+/// The abstract base class for an HTTP client.
+///
+/// Subclasses only need to implement [send] and maybe [close], and then they
 /// get various convenience methods for free.
 abstract class BaseClient implements Client {
-  /// Sends an HTTP HEAD request with the given headers to the given URL, which
-  /// can be a [Uri] or a [String].
-  ///
-  /// For more fine-grained control over the request, use [send] instead.
   Future<Response> head(url, {Map<String, String> headers}) =>
       send(new Request.head(url, headers: headers));
 
-  /// Sends an HTTP GET request with the given headers to the given URL, which
-  /// can be a [Uri] or a [String].
-  ///
-  /// For more fine-grained control over the request, use [send] instead.
   Future<Response> get(url, {Map<String, String> headers}) =>
       send(new Request.get(url, headers: headers));
 
-  /// Sends an HTTP POST request with the given headers and body to the given
-  /// URL, which can be a [Uri] or a [String].
-  ///
-  /// [body] sets the body of the request. It can be a [String], a [List<int>]
-  /// or a [Map<String, String>]. If it's a String, it's encoded using
-  /// [encoding] and used as the body of the request. The content-type of the
-  /// request will default to "text/plain".
-  ///
-  /// If [body] is a List, it's used as a list of bytes for the body of the
-  /// request.
-  ///
-  /// If [body] is a Map, it's encoded as form fields using [encoding]. The
-  /// content-type of the request will be set to
-  /// `"application/x-www-form-urlencoded"`; this cannot be overridden.
-  ///
-  /// [encoding] defaults to UTF-8.
-  ///
-  /// For more fine-grained control over the request, use [send] instead.
   Future<Response> post(url, body,
           {Map<String, String> headers, Encoding encoding}) =>
       send(new Request.post(url, body, headers: headers, encoding: encoding));
 
-  /// Sends an HTTP PUT request with the given headers and body to the given
-  /// URL, which can be a [Uri] or a [String].
-  ///
-  /// [body] sets the body of the request. It can be a [String], a [List<int>]
-  /// or a [Map<String, String>]. If it's a String, it's encoded using
-  /// [encoding] and used as the body of the request. The content-type of the
-  /// request will default to "text/plain".
-  ///
-  /// If [body] is a List, it's used as a list of bytes for the body of the
-  /// request.
-  ///
-  /// If [body] is a Map, it's encoded as form fields using [encoding]. The
-  /// content-type of the request will be set to
-  /// `"application/x-www-form-urlencoded"`; this cannot be overridden.
-  ///
-  /// [encoding] defaults to UTF-8.
-  ///
-  /// For more fine-grained control over the request, use [send] instead.
   Future<Response> put(url, body,
           {Map<String, String> headers, Encoding encoding}) =>
       send(new Request.put(url, body, headers: headers, encoding: encoding));
 
-  /// Sends an HTTP PATCH request with the given headers and body to the given
-  /// URL, which can be a [Uri] or a [String].
-  ///
-  /// [body] sets the body of the request. It can be a [String], a [List<int>]
-  /// or a [Map<String, String>]. If it's a String, it's encoded using
-  /// [encoding] and used as the body of the request. The content-type of the
-  /// request will default to "text/plain".
-  ///
-  /// If [body] is a List, it's used as a list of bytes for the body of the
-  /// request.
-  ///
-  /// If [body] is a Map, it's encoded as form fields using [encoding]. The
-  /// content-type of the request will be set to
-  /// `"application/x-www-form-urlencoded"`; this cannot be overridden.
-  ///
-  /// [encoding] defaults to UTF-8.
-  ///
-  /// For more fine-grained control over the request, use [send] instead.
   Future<Response> patch(url, body,
           {Map<String, String> headers, Encoding encoding}) =>
       send(new Request.patch(url, body, headers: headers, encoding: encoding));
 
-  /// Sends an HTTP DELETE request with the given headers to the given URL,
-  /// which can be a [Uri] or a [String].
-  ///
-  /// For more fine-grained control over the request, use [send] instead.
   Future<Response> delete(url, {Map<String, String> headers}) =>
       send(new Request.delete(url, headers: headers));
 
-  /// Sends an HTTP GET request with the given headers to the given URL, which
-  /// can be a [Uri] or a [String], and returns a Future that completes to the
-  /// body of the response as a String.
-  ///
-  /// The Future will emit a [ClientException] if the response doesn't have a
-  /// success status code.
-  ///
-  /// For more fine-grained control over the request and response, use [send] or
-  /// [get] instead.
   Future<String> read(url, {Map<String, String> headers}) async {
     var response = await get(url, headers: headers);
     _checkResponseSuccess(url, response);
 
     return await response.readAsString();
   }
 
-  /// Sends an HTTP GET request with the given headers to the given URL, which
-  /// can be a [Uri] or a [String], and returns a Future that completes to the
-  /// body of the response as a list of bytes.
-  ///
-  /// The Future will emit an [ClientException] if the response doesn't have a
-  /// success status code.
-  ///
-  /// For more fine-grained control over the request and response, use [send] or
-  /// [get] instead.
   Future<Uint8List> readBytes(url, {Map<String, String> headers}) async {
     var response = await get(url, headers: headers);
     _checkResponseSuccess(url, response);
 
     return await collectBytes(response.read());
   }
 
-  /// Sends an HTTP request and asynchronously returns the response.
-  ///
-  /// Implementers should call [BaseRequest.finalize] to get the body of the
-  /// request as a [ByteStream]. They shouldn't make any assumptions about the
-  /// state of the stream; it could have data written to it asynchronously at a
-  /// later point, or it could already be closed when it's returned. Any
-  /// internal HTTP errors should be wrapped as [ClientException]s.
   Future<Response> send(Request request);
 
   /// Throws an error if [response] is not successful.
@@ -156,8 +66,5 @@ abstract class BaseClient implements Client {
     throw new ClientException("$message.", url);
   }
 
-  /// Closes the client and cleans up any resources associated with it. It's
-  /// important to close each client when it's done being used; failing to do so
-  /// can cause the Dart process to hang.
   void close() {}
 }

lib/src/client.dart

@@ -145,8 +145,9 @@ abstract class Client {
   /// Sends an HTTP request and asynchronously returns the response.
   Future<Response> send(Request request);
 
-  /// Closes the client and cleans up any resources associated with it. It's
-  /// important to close each client when it's done being used; failing to do so
-  /// can cause the Dart process to hang.
+  /// Closes the client and cleans up any resources associated with it.
+  ///
+  /// It's important to close each client when it's done being used; failing to
+  /// do so can cause the Dart process to hang.
   void close();
 }

lib/src/exception.dart

@@ -4,11 +4,15 @@
 
 /// An exception caused by an error in a pkg/http client.
 class ClientException implements Exception {
+  /// Message describing the problem.
   final String message;
 
   /// The URL of the HTTP request or response that failed.
   final Uri uri;
 
+  /// Creates a [ClientException] explained in [message].
+  ///
+  /// The [uri] points to the URL being requested if applicable.
   ClientException(this.message, [this.uri]);
 
   String toString() => message;

lib/src/io_client.dart

@@ -22,7 +22,6 @@ class IOClient extends BaseClient {
   /// Creates a new HTTP client.
   IOClient([HttpClient inner]) : _inner = inner ?? new HttpClient();
 
-  /// Sends an HTTP request and asynchronously returns the response.
   Future<Response> send(Request request) async {
     try {
       var ioRequest = await _inner.openUrl(request.method, request.url);
@@ -57,8 +56,6 @@ class IOClient extends BaseClient {
     }
   }
 
-  /// Closes the client. This terminates all active connections. If a client
-  /// remains unclosed, the Dart process may not terminate.
   void close() {
     if (_inner != null) _inner.close(force: true);
     _inner = null;

lib/src/multipart_body.dart

@@ -84,9 +84,6 @@ class MultipartBody implements Body {
 
   MultipartBody._(this._stream, this.contentLength);
 
-  /// Returns a [Stream] representing the body.
-  ///
-  /// Can only be called once.
   Stream<List<int>> read() {
     if (_stream == null) {
       throw new StateError("The 'read' method can only be called once on a "

lib/src/pipeline.dart

@@ -20,6 +20,7 @@ class Pipeline {
   /// The [Middleware] that is invoked at this stage.
   final Middleware _middleware;
 
+  /// Creates a [Pipeline].
   const Pipeline()
       : _parent = null,
         _middleware = null;

lib/src/utils.dart

@@ -45,8 +45,8 @@ bool isPlainAscii(String string) => _asciiOnly.hasMatch(string);
 
 /// Pipes all data and errors from [stream] into [sink].
 ///
-/// Completes [Future] once [stream] is done. Unlike [store], [sink] remains
-/// open after [stream] is done.
+/// Completes [Future] once [stream] is done. [sink] remains open after [stream]
+/// is done.
 Future writeStreamToSink(Stream stream, EventSink sink) {
   var completer = new Completer();
   stream.listen(sink.add,