Fix return type of Base64Codec.decode to say Uint8List.

Update some documentation.

Change-Id: I4e05d89e84bd35068ca57917e752af235c62b647
Reviewed-on: https://dart-review.googlesource.com/32762
Reviewed-by: Erik Ernst <eernst@google.com>
Commit-Queue: Lasse R.H. Nielsen <lrn@google.com>

CHANGELOG.md

@@ -56,6 +56,7 @@
   * Renamed the `HtmlEscapeMode` constants `UNKNOWN`, `ATTRIBUTE`,
     `SQ_ATTRIBUTE` and `ELEMENT` to `unknown`, `attribute`, `sqAttribute` and
     `elements`.
+  * Changed return type of `Base64Codec.decode` to `Uint8List`.
 
 * `dart:developer`
   * `Timeline.startSync` and `Timeline.timeSync` now accept an optional

sdk/lib/convert/base64.dart

@@ -62,6 +62,17 @@ class Base64Codec extends Codec<List<int>, String> {
 
   Base64Decoder get decoder => const Base64Decoder();
 
+  /**
+   * Decodes [encoded].
+   *
+   * The input is decoded as if by `decoder.convert`.
+   *
+   * The returned [Uint8List] contains exactly the decoded bytes,
+   * so the [Uint8List.length] is precisely the number of decoded bytes.
+   * The [Uint8List.buffer] may be larger than the decoded bytes.
+   */
+  Uint8List decode(String encoded) => decoder.convert(encoded);
+
   /**
    * Validates and normalizes the base64 encoded data in [source].
    *
@@ -471,7 +482,17 @@ class _Utf8Base64EncoderSink extends _Base64EncoderSink {
 class Base64Decoder extends Converter<String, List<int>> {
   const Base64Decoder();
 
-  List<int> convert(String input, [int start = 0, int end]) {
+  /**
+   * Decodes the characters of [input] from [start] to [end] as base64.
+   *
+   * If [start] is omitted, it defaults to the start of [input].
+   * If [end] is omitted, it defaults to the end of [input].
+   *
+   * The returned [Uint8List] contains exactly the decoded bytes,
+   * so the [Uint8List.length] is precisely the number of decoded bytes.
+   * The [Uint8List.buffer] may be larger than the decoded bytes.
+   */
+  Uint8List convert(String input, [int start = 0, int end]) {
     end = RangeError.checkValidRange(start, end, input.length);
     if (start == end) return new Uint8List(0);
     var decoder = new _Base64Decoder();

sdk/lib/convert/codec.dart

@@ -17,7 +17,18 @@ part of dart.convert;
 abstract class Codec<S, T> {
   const Codec();
 
+  /**
+   * Encodes [input].
+   *
+   * The input is encoded as if by `encoder.convert`.
+   */
   T encode(S input) => encoder.convert(input);
+
+  /**
+   * Decodes [encoded] data.
+   *
+   * The input is decoded as if by `decoder.convert`.
+   */
   S decode(T encoded) => decoder.convert(encoded);
 
   /**

sdk/lib/isolate/isolate.dart

@@ -156,7 +156,7 @@ class Isolate {
   external static Isolate get current;
 
   /**
-   * Returns the package root of the current isolate, if any.
+   * The location of the package configuration of the current isolate, if any.
    *
    * If the isolate is using a [packageConfig] or the isolate has not been
    * setup for package resolution, this getter returns `null`, otherwise it
@@ -166,7 +166,7 @@ class Isolate {
   external static Future<Uri> get packageRoot;
 
   /**
-   * Returns the package root of the current isolate, if any.
+   * The package root of the current isolate, if any.
    *
    * If the isolate is using a [packageRoot] or the isolate has not been
    * setup for package resolution, this getter returns `null`, otherwise it