Random fixes to dartdocs, http lib, analyzer

This is a variety of trivial fixes that I collected while going through the dartdocs.
This does contain some non-comment changes.

packages/flutter/lib/http.dart

@@ -2,14 +2,15 @@
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
-/// Service exposed to Flutter apps that implements a subset of Dart's
-/// http package API.
+/// A [Future]-based library for making HTTP requests.
 ///
-/// This library will probably be moved into a separate package eventually.
+/// This library is based on Dart's `http` package, but differs in that it is a
+/// `mojo`-based HTTP client and does not have a dependency on mirrors.
 ///
 /// This library depends only on core Dart libraries as well as the `mojo`,
-/// `mojo_services`, and `sky_services` and packages.
+/// `mojo_services`, and `sky_services` packages.
 library http;
 
 export 'src/http/http.dart';
+export 'src/http/mojo_client.dart';
 export 'src/http/response.dart';

packages/flutter/lib/src/http/http.dart

@@ -2,12 +2,6 @@
 // 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.
 
-/// A [Future]-based library for making HTTP requests.
-///
-/// This library is based on Dart's `http` package, but we have removed the
-/// dependency on mirrors and added a `mojo`-based HTTP client.
-library http;
-
 import 'dart:async';
 import 'dart:convert';
 import 'dart:typed_data';
@@ -18,28 +12,48 @@ import 'response.dart';
 /// Sends an HTTP HEAD request with the given headers to the given URL, which
 /// can be a [Uri] or a [String].
 ///
-/// This automatically initializes a new [Client] and closes that client once
+/// This automatically initializes a new [MojoClient] 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) =>
-  _withClient((client) => client.head(url));
+/// the same server, you should use a single [MojoClient] for all of those requests.
+Future<Response> head(dynamic url) {
+  return _withClient/*<Response>*/((MojoClient client) => client.head(url));
+}
 
 /// Sends an HTTP GET request with the given headers to the given URL, which can
 /// be a [Uri] or a [String].
 ///
-/// This automatically initializes a new [Client] and closes that client once
+/// This automatically initializes a new [MojoClient] 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));
+/// the same server, you should use a single [MojoClient] for all of those requests.
+Future<Response> get(dynamic url, { Map<String, String> headers }) {
+  return _withClient/*<Response>*/((MojoClient client) => client.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.
-Future<Response> post(url, {Map<String, String> headers, body}) =>
-  _withClient((client) => client.post(url,
-      headers: headers, body: body));
+/// [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 [UTF8].
+///
+/// This automatically initializes a new [MojoClient] 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 [MojoClient] for all of those requests.
+Future<Response> post(dynamic url, { Map<String, String> headers, dynamic body, Encoding encoding: UTF8 }) {
+  return _withClient/*<Response>*/((MojoClient client) {
+    return client.post(url, headers: headers, body: body, 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].
@@ -48,9 +62,24 @@ Future<Response> post(url, {Map<String, String> headers, body}) =>
 /// 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".
-Future<Response> put(url, {Map<String, String> headers, body}) =>
-  _withClient((client) => client.put(url,
-      headers: headers, body: body));
+///
+/// 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 [UTF8].
+///
+/// This automatically initializes a new [MojoClient] 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 [MojoClient] for all of those requests.
+Future<Response> put(dynamic url, { Map<String, String> headers, dynamic body, Encoding encoding: UTF8 }) {
+  return _withClient/*<Response>*/((MojoClient client) {
+    return client.put(url, headers: headers, body: body, 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].
@@ -69,22 +98,24 @@ Future<Response> put(url, {Map<String, String> headers, body}) =>
 ///
 /// [encoding] defaults to [UTF8].
 ///
-/// For more fine-grained control over the request, use [Request] or
-/// [StreamedRequest] instead.
-Future<Response> patch(url, {Map<String, String> headers, body}) =>
-  _withClient((client) => client.patch(url,
-      headers: headers, body: body));
+/// This automatically initializes a new [MojoClient] 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 [MojoClient] for all of those requests.
+Future<Response> patch(dynamic url, { Map<String, String> headers, dynamic body, Encoding encoding: UTF8 }) {
+  return _withClient/*<Response>*/((MojoClient client) {
+     return client.patch(url, headers: headers, body: body, encoding: encoding);
+  });
+}
 
 /// Sends an HTTP DELETE request with the given headers to the given URL, which
 /// can be a [Uri] or a [String].
 ///
-/// This automatically initializes a new [Client] and closes that client once
+/// This automatically initializes a new [MojoClient] 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));
+/// the same server, you should use a single [MojoClient] for all of those requests.
+Future<Response> delete(dynamic url, { Map<String, String> headers }) {
+  return _withClient/*<Response>*/((MojoClient client) => client.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
@@ -93,14 +124,12 @@ Future<Response> delete(url, {Map<String, String> headers}) =>
 /// The Future will emit a [ClientException] if the response doesn't have a
 /// success status code.
 ///
-/// This automatically initializes a new [Client] and closes that client once
+/// This automatically initializes a new [MojoClient] 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));
+/// the same server, you should use a single [MojoClient] for all of those requests.
+Future<String> read(dynamic url, { Map<String, String> headers }) {
+  return _withClient/*<String>*/((MojoClient client) => client.read(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
@@ -109,17 +138,13 @@ Future<String> read(url, {Map<String, String> headers}) =>
 /// The Future will emit a [ClientException] if the response doesn't have a
 /// success status code.
 ///
-/// This automatically initializes a new [Client] and closes that client once
+/// This automatically initializes a new [MojoClient] 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));
+/// the same server, you should use a single [MojoClient] for all of those requests.
+Future<Uint8List> readBytes(dynamic url, { Map<String, String> headers }) {
+  return _withClient/*<Uint8List>*/((MojoClient client) => client.readBytes(url, headers: headers));
+}
 
-Future _withClient(Future fn(MojoClient client)) {
-  var client = new MojoClient();
-  var future = fn(client);
-  return future.whenComplete(client.close);
+Future/*<T>*/ _withClient/*<T>*/(Future/*<T>*/ fn(MojoClient client)) {
+  return fn(new MojoClient());
 }

packages/flutter/lib/src/http/mojo_client.dart

@@ -19,43 +19,111 @@ import 'response.dart';
 /// A `mojo`-based HTTP client.
 class MojoClient {
 
-  Future<Response> head(url, {Map<String, String> headers}) =>
-    _send("HEAD", url, headers);
+  /// Sends an HTTP HEAD request with the given headers to the given URL, which
+  /// can be a [Uri] or a [String].
+  Future<Response> head(dynamic url, { Map<String, String> headers }) {
+    return _send("HEAD", url, headers);
+  }
 
-  Future<Response> get(url, {Map<String, String> headers}) =>
-    _send("GET", url, headers);
+  /// Sends an HTTP GET request with the given headers to the given URL, which can
+  /// be a [Uri] or a [String].
+  Future<Response> get(dynamic url, { Map<String, String> headers }) {
+    return _send("GET", url, headers);
+  }
 
-  Future<Response> post(url, {Map<String, String> headers, body,
-      Encoding encoding}) =>
-    _send("POST", url, headers, body, encoding);
+  /// 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 [UTF8].
+  Future<Response> post(dynamic url, { Map<String, String> headers, dynamic body, Encoding encoding: UTF8 }) {
+    return _send("POST", url, headers, body, encoding);
+  }
 
-  Future<Response> put(url, {Map<String, String> headers, body,
-      Encoding encoding}) =>
-    _send("PUT", url, headers, body, 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 [UTF8].
+  Future<Response> put(dynamic url, { Map<String, String> headers, dynamic body, Encoding encoding: UTF8 }) {
+    return _send("PUT", url, headers, body, encoding);
+  }
 
-  Future<Response> patch(url, {Map<String, String> headers, body,
-      Encoding encoding}) =>
-    _send("PATCH", url, headers, body, 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 [UTF8].
+  Future<Response> patch(dynamic url, {Map<String, String> headers, dynamic body, Encoding encoding: UTF8 }) {
+    return _send("PATCH", url, headers, body, encoding);
+  }
 
-  Future<Response> delete(url, {Map<String, String> headers}) =>
-    _send("DELETE", url, headers);
+  /// Sends an HTTP DELETE request with the given headers to the given URL, which
+  /// can be a [Uri] or a [String].
+  Future<Response> delete(dynamic url, { Map<String, String> headers }) {
+    return _send("DELETE", url, headers);
+  }
 
-  Future<String> read(url, {Map<String, String> headers}) {
-    return get(url, headers: headers).then((response) {
+  /// 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.
+  Future<String> read(dynamic url, { Map<String, String> headers }) {
+    return get(url, headers: headers).then((Response response) {
       _checkResponseSuccess(url, response);
       return response.body;
     });
   }
 
-  Future<Uint8List> readBytes(url, {Map<String, String> 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 list of bytes.
+  ///
+  /// The Future will emit a [ClientException] if the response doesn't have a
+  /// success status code.
+  Future<Uint8List> readBytes(dynamic url, { Map<String, String> headers }) {
     return get(url, headers: headers).then((Response response) {
       _checkResponseSuccess(url, response);
       return response.bodyBytes;
     });
   }
 
-  Future<Response> _send(String method, url,
-      Map<String, String> headers, [body, Encoding encoding]) async {
+  Future<Response> _send(String method, dynamic url, Map<String, String> headers, [dynamic body, Encoding encoding = UTF8]) async {
     mojo.UrlLoaderProxy loader = new mojo.UrlLoaderProxy.unbound();
     List<mojo.HttpHeader> mojoHeaders = <mojo.HttpHeader>[];
     headers?.forEach((String name, String value) {
@@ -71,7 +139,7 @@ class MojoClient {
     if (body != null) {
       mojo.MojoDataPipe pipe = new mojo.MojoDataPipe();
       request.body = <mojo.MojoDataPipeConsumer>[pipe.consumer];
-      Uint8List encodedBody = UTF8.encode(body);
+      Uint8List encodedBody = encoding.encode(body);
       ByteData data = new ByteData.view(encodedBody.buffer);
       mojo.DataPipeFiller.fillHandle(pipe.producer, data);
     }
@@ -90,14 +158,12 @@ class MojoClient {
     }
   }
 
-  void _checkResponseSuccess(url, Response response) {
+  void _checkResponseSuccess(dynamic url, Response response) {
     if (response.statusCode < 400)
       return;
     throw new Exception("Request to $url failed with status ${response.statusCode}.");
   }
 
-  void close() {}
-
   static mojo.NetworkServiceProxy _initNetworkService() {
     mojo.NetworkServiceProxy proxy = new mojo.NetworkServiceProxy.unbound();
     shell.connectToService("mojo:authenticated_network_service", proxy);

packages/flutter/lib/src/material/shadows.dart

@@ -10,11 +10,20 @@ import 'package:flutter/painting.dart';
 // Currently, only the elevation values that are bound to one or more components are
 // defined here.
 
+/// Map of elevation offsets used by material design to [BoxShadow] definitions.
+///
+/// The following elevations have defined shadows: 1, 2, 3, 4, 6, 8, 9, 12, 16, 24
+///
+/// Each entry has three shadows which must be combined to obtain the defined
+/// effect for that elevation.
+///
+/// See also: <https://www.google.com/design/spec/what-is-material/elevation-shadows.html>
+const Map<int, List<BoxShadow>> elevationToShadow = _elevationToShadow; // to hide the literal from the docs
+
 const Color _kKeyUmbraOpacity = const Color(0x33000000); // alpha = 0.2
 const Color _kKeyPenumbraOpacity = const Color(0x24000000); // alpha = 0.14
 const Color _kAmbientShadowOpacity = const Color(0x1F000000); // alpha = 0.12
-
-const Map<int, List<BoxShadow>> elevationToShadow = const <int, List<BoxShadow>>{
+const Map<int, List<BoxShadow>> _elevationToShadow = const <int, List<BoxShadow>>{
   1: const <BoxShadow>[
     const BoxShadow(offset: const Offset(0.0, 2.0), blurRadius: 1.0, spreadRadius: -1.0, color: _kKeyUmbraOpacity),
     const BoxShadow(offset: const Offset(0.0, 1.0), blurRadius: 1.0, spreadRadius: 0.0, color: _kKeyPenumbraOpacity),

packages/flutter/lib/src/rendering/debug.dart

@@ -53,7 +53,7 @@ bool debugPaintPointersEnabled = false;
 /// The color to use when reporting pointers.
 int debugPaintPointersColorValue = 0x00BBBB;
 
-/// The color to use when painting RenderError boxes in checked mode.
+/// The color to use when painting [RenderErrorBox] objects in checked mode.
 Color debugErrorBoxColor = const Color(0xFFFF0000);
 
 /// Overlay a rotating set of colors when repainting layers in checked mode.

packages/flutter/lib/src/scheduler/ticker.dart

@@ -6,11 +6,12 @@ import 'dart:async';
 
 import 'scheduler.dart';
 
+/// Signature for the [onTick] constructor argument of the [Ticker] class.
 typedef void TickerCallback(Duration elapsed);
 
 /// Calls its callback once per animation frame.
 class Ticker {
-  /// Constructs a ticker that will call onTick once per frame while running
+  /// Constructs a ticker that will call [onTick] once per frame while running.
   Ticker(TickerCallback onTick) : _onTick = onTick;
 
   final TickerCallback _onTick;

packages/flutter_tools/lib/src/commands/analyze.dart

@@ -334,7 +334,7 @@ linter:
       if (dartFiles.length == 1) {
         printStatus('Analyzing ${dartFiles.first}...');
       } else {
-        printStatus('Analyzing ${dartFiles.length} files...');
+        printStatus('Analyzing ${dartFiles.length} entry points...');
       }
       for (String file in dartFiles)
         printTrace(file);