Skip to content

Commit

Permalink
Documentation cleanup (#132)
Browse files Browse the repository at this point in the history
  • Loading branch information
@donny-dont @nex3
donny-dont authored and nex3 committed Oct 26, 2017
1 parent 6d3d7c5 commit fc32f51
Show file tree
Hide file tree
Showing 9 changed files with 33 additions and 132 deletions.
13 changes: 4 additions & 9 deletions lib/browser_client.dart
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
///
Expand All @@ -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();
Expand Down Expand Up @@ -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();
Expand Down
31 changes: 15 additions & 16 deletions lib/http.dart
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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));

Expand All @@ -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));

Expand All @@ -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) =>
Expand All @@ -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) =>
Expand All @@ -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) =>
Expand All @@ -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));

Expand All @@ -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));

Expand All @@ -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));

Expand Down
99 changes: 3 additions & 96 deletions lib/src/base_client.dart
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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() {}
}
7 changes: 4 additions & 3 deletions lib/src/client.dart
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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();
}
4 changes: 4 additions & 0 deletions lib/src/exception.dart
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down
3 changes: 0 additions & 3 deletions lib/src/io_client.dart
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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);
Expand Down Expand Up @@ -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;
Expand Down
3 changes: 0 additions & 3 deletions lib/src/multipart_body.dart
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 "
Expand Down
1 change: 1 addition & 0 deletions lib/src/pipeline.dart
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down
4 changes: 2 additions & 2 deletions lib/src/utils.dart
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down

0 comments on commit fc32f51

Please sign in to comment.