Clean up doc comment style (#315)

- Delete doc comments that add no new information.
- Add some details to otherwise non-informative comments.
- Consistently use a blank line following the first sentence.
- Change some wording for style.
- Remove unnecessary `new` in code examples.

Author: natebosch

README.md

@@ -28,7 +28,7 @@ persistent connection by using a [Client][] rather than making one-off requests.
 If you do this, make sure to close the client when you're done:
 
 ```dart
-var client = new http.Client();
+var client = http.Client();
 try {
   var uriResponse = await client.post('https://example.com/whatsit/create',
       body: {'name': 'doodle', 'color': 'blue'});

lib/src/base_client.dart

@@ -13,9 +13,10 @@ import 'request.dart';
 import 'response.dart';
 import 'streamed_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
-/// get various convenience methods for free.
+/// 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 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].
@@ -189,9 +190,10 @@ abstract class BaseClient implements Client {
     throw 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.
+  /// 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.
   @override
   void close() {}
 }

lib/src/base_request.dart

@@ -17,9 +17,10 @@ import 'utils.dart';
 /// over the request properties. However, usually it's easier to use convenience
 /// methods like [get] or [BaseClient.get].
 abstract class BaseRequest {
-  /// The HTTP method of the request. Most commonly "GET" or "POST", less
-  /// commonly "HEAD", "PUT", or "DELETE". Non-standard method names are also
-  /// supported.
+  /// The HTTP method of the request.
+  ///
+  /// Most commonly "GET" or "POST", less commonly "HEAD", "PUT", or "DELETE".
+  /// Non-standard method names are also supported.
   final String method;
 
   /// The URL to which the request will be sent.
@@ -28,7 +29,7 @@ abstract class BaseRequest {
   /// The size of the request body, in bytes.
   ///
   /// This defaults to `null`, which indicates that the size of the request is
-  /// not known in advance.
+  /// not known in advance. May not be assigned a negative value.
   int get contentLength => _contentLength;
   int _contentLength;
 
@@ -41,6 +42,7 @@ abstract class BaseRequest {
   }
 
   /// Whether a persistent connection should be maintained with the server.
+  ///
   /// Defaults to true.
   bool get persistentConnection => _persistentConnection;
   bool _persistentConnection = true;
@@ -51,6 +53,7 @@ abstract class BaseRequest {
   }
 
   /// Whether the client should follow redirects while resolving this request.
+  ///
   /// Defaults to true.
   bool get followRedirects => _followRedirects;
   bool _followRedirects = true;
@@ -61,6 +64,7 @@ abstract class BaseRequest {
   }
 
   /// The maximum number of redirects to follow when [followRedirects] is true.
+  ///
   /// If this number is exceeded the [BaseResponse] future will signal a
   /// [RedirectException]. Defaults to 5.
   int get maxRedirects => _maxRedirects;
@@ -74,22 +78,21 @@ abstract class BaseRequest {
   // TODO(nweiz): automatically parse cookies from headers
 
   // TODO(nweiz): make this a HttpHeaders object
-  /// The headers for this request.
   final Map<String, String> headers;
 
-  /// Whether the request has been finalized.
+  /// Whether [finalize] has been called.
   bool get finalized => _finalized;
   bool _finalized = false;
 
-  /// Creates a new HTTP request.
   BaseRequest(this.method, this.url)
       : headers = LinkedHashMap(
             equals: (key1, key2) => key1.toLowerCase() == key2.toLowerCase(),
             hashCode: (key) => key.toLowerCase().hashCode);
 
-  /// Finalizes the HTTP request in preparation for it being sent. This freezes
-  /// all mutable fields and returns a single-subscription [ByteStream] that
-  /// emits the body of the request.
+  /// Finalizes the HTTP request in preparation for it being sent.
+  ///
+  /// Freezes all mutable fields and returns a single-subscription [ByteStream]
+  /// that emits the body of the request.
   ///
   /// The base implementation of this returns null rather than a [ByteStream];
   /// subclasses are responsible for creating the return value, which should be
@@ -128,7 +131,7 @@ abstract class BaseRequest {
     }
   }
 
-  // Throws an error if this request has been finalized.
+  /// Throws an error if this request has been finalized.
   void _checkFinalized() {
     if (!finalized) return;
     throw StateError("Can't modify a finalized Request.");

lib/src/base_response.dart

@@ -12,7 +12,7 @@ abstract class BaseResponse {
   /// The (frozen) request that triggered this response.
   final BaseRequest request;
 
-  /// The status code of the response.
+  /// The HTTP status code for this response.
   final int statusCode;
 
   /// The reason phrase associated with the status code.
@@ -26,16 +26,13 @@ abstract class BaseResponse {
   // TODO(nweiz): automatically parse cookies from headers
 
   // TODO(nweiz): make this a HttpHeaders object.
-  /// The headers for this response.
   final Map<String, String> headers;
 
-  /// Whether this response is a redirect.
   final bool isRedirect;
 
   /// Whether the server requested that a persistent connection be maintained.
   final bool persistentConnection;
 
-  /// Creates a new HTTP response.
   BaseResponse(this.statusCode,
       {this.contentLength,
       this.request,

lib/src/boundary_characters.dart

@@ -2,10 +2,11 @@
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
-/// All character codes that are valid in multipart boundaries. This is the
-/// intersection of the characters allowed in the `bcharsnospace` production
-/// defined in [RFC 2046][] and those allowed in the `token` production
-/// defined in [RFC 1521][].
+/// All character codes that are valid in multipart boundaries.
+///
+/// This is the intersection of the characters allowed in the `bcharsnospace`
+/// production defined in [RFC 2046][] and those allowed in the `token`
+/// production defined in [RFC 1521][].
 ///
 /// [RFC 2046]: http://tools.ietf.org/html/rfc2046#section-5.1.1.
 /// [RFC 1521]: https://tools.ietf.org/html/rfc1521#section-4

lib/src/browser_client.dart

@@ -14,6 +14,8 @@ import 'byte_stream.dart';
 import 'exception.dart';
 import 'streamed_response.dart';
 
+/// Create a [BrowserClient].
+///
 /// Used from conditional imports, matches the definition in `client_stub.dart`.
 BaseClient createClient() => BrowserClient();
 
@@ -31,9 +33,6 @@ class BrowserClient extends BaseClient {
   /// These are aborted if the client is closed.
   final _xhrs = <HttpRequest>{};
 
-  /// Creates a new HTTP client.
-  BrowserClient();
-
   /// Whether to send credentials such as cookies or authorization headers for
   /// cross-site requests.
   ///

lib/src/client.dart

@@ -18,20 +18,20 @@ import 'response.dart';
 import 'streamed_response.dart';
 
 /// The interface for HTTP clients that take care of maintaining persistent
-/// connections across multiple requests to the same server. If you only need to
-/// send a single request, it's usually easier to use [head], [get], [post],
-/// [put], [patch], or [delete] instead.
+/// connections across multiple requests to the same server.
+///
+/// If you only need to send a single request, it's usually easier to use
+/// [head], [get], [post], [put], [patch], or [delete] instead.
 ///
 /// When creating an HTTP client class with additional functionality, you must
 /// extend [BaseClient] rather than [Client]. In most cases, you can wrap
 /// another instance of [Client] and add functionality on top of that. This
 /// allows all classes implementing [Client] to be mutually composable.
 abstract class Client {
-  /// Creates a new client.
+  /// Creates a new platform appropriate client.
   ///
-  /// Currently this will create an `IOClient` if `dart:io` is available and
-  /// a `BrowserClient` if `dart:html` is available, otherwise it will throw
-  /// an unsupported error.
+  /// Creates an `IOClient` if `dart:io` is available and a `BrowserClient` if
+  /// `dart:html` is available, otherwise it will throw an unsupported error.
   factory Client() => createClient();
 
   /// Sends an HTTP HEAD request with the given headers to the given URL, which
@@ -140,8 +140,9 @@ abstract class Client {
   /// Sends an HTTP request and asynchronously returns the response.
   Future<StreamedResponse> send(BaseRequest 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/io_client.dart

@@ -12,17 +12,16 @@ import 'base_request.dart';
 import 'exception.dart';
 import 'streamed_response.dart';
 
+/// Create an [IOClient].
+///
 /// Used from conditional imports, matches the definition in `client_stub.dart`.
 BaseClient createClient() => IOClient();
 
 /// A `dart:io`-based HTTP client.
-///
-/// This is the default client when running on the command line.
 class IOClient extends BaseClient {
   /// The underlying `dart:io` HTTP client.
   HttpClient _inner;
 
-  /// Creates a new HTTP client.
   IOClient([HttpClient inner]) : _inner = inner ?? HttpClient();
 
   /// Sends an HTTP request and asynchronously returns the response.
@@ -64,8 +63,10 @@ class IOClient extends BaseClient {
     }
   }
 
-  /// Closes the client. This terminates all active connections. If a client
-  /// remains unclosed, the Dart process may not terminate.
+  /// Closes the client.
+  ///
+  /// Terminates all active connections. If a client remains unclosed, the Dart
+  /// process may not terminate.
   @override
   void close() {
     if (_inner != null) {

lib/src/mock_client.dart

@@ -15,9 +15,11 @@ import 'streamed_response.dart';
 // server APIs, MockClient should conform to it.
 
 /// A mock HTTP client designed for use when testing code that uses
-/// [BaseClient]. This client allows you to define a handler callback for all
-/// requests that are made through it so that you can mock a server without
-/// having to send real HTTP requests.
+/// [BaseClient].
+///
+/// This client allows you to define a handler callback for all requests that
+/// are made through it so that you can mock a server without having to send
+/// real HTTP requests.
 class MockClient extends BaseClient {
   /// The handler for receiving [StreamedRequest]s and sending
   /// [StreamedResponse]s.
@@ -66,7 +68,6 @@ class MockClient extends BaseClient {
           });
         });
 
-  /// Sends a request.
   @override
   Future<StreamedResponse> send(BaseRequest request) async {
     var bodyStream = request.finalize();
@@ -75,10 +76,13 @@ class MockClient extends BaseClient {
 }
 
 /// A handler function that receives [StreamedRequest]s and sends
-/// [StreamedResponse]s. Note that [request] will be finalized.
+/// [StreamedResponse]s.
+///
+/// Note that [request] will be finalized.
 typedef MockClientStreamHandler = Future<StreamedResponse> Function(
     BaseRequest request, ByteStream bodyStream);
 
-/// A handler function that receives [Request]s and sends [Response]s. Note that
-/// [request] will be finalized.
+/// A handler function that receives [Request]s and sends [Response]s.
+///
+/// Note that [request] will be finalized.
 typedef MockClientHandler = Future<Response> Function(Request request);

lib/src/multipart_file.dart

@@ -14,20 +14,27 @@ import 'multipart_file_stub.dart'
     if (dart.library.io) 'multipart_file_io.dart';
 import 'utils.dart';
 
-/// A file to be uploaded as part of a [MultipartRequest]. This doesn't need to
-/// correspond to a physical file.
+/// A file to be uploaded as part of a [MultipartRequest].
+///
+/// This doesn't need to correspond to a physical file.
 class MultipartFile {
   /// The name of the form field for the file.
   final String field;
 
-  /// The size of the file in bytes. This must be known in advance, even if this
-  /// file is created from a [ByteStream].
+  /// The size of the file in bytes.
+  ///
+  /// This must be known in advance, even if this file is created from a
+  /// [ByteStream].
   final int length;
 
-  /// The basename of the file. May be null.
+  /// The basename of the file.
+  ///
+  /// May be null.
   final String filename;
 
-  /// The content-type of the file. Defaults to `application/octet-stream`.
+  /// The content-type of the file.
+  ///
+  /// Defaults to `application/octet-stream`.
   final MediaType contentType;
 
   /// The stream that will emit the file's contents.
@@ -37,9 +44,10 @@ class MultipartFile {
   bool get isFinalized => _isFinalized;
   bool _isFinalized = false;
 
-  /// Creates a new [MultipartFile] from a chunked [Stream] of bytes. The length
-  /// of the file in bytes must be known in advance. If it's not, read the data
-  /// from the stream and use [MultipartFile.fromBytes] instead.
+  /// Creates a new [MultipartFile] from a chunked [Stream] of bytes.
+  ///
+  /// The length of the file in bytes must be known in advance. If it's not,
+  /// read the data from the stream and use [MultipartFile.fromBytes] instead.
   ///
   /// [contentType] currently defaults to `application/octet-stream`, but in the
   /// future may be inferred from [filename].