Update documentation comments.

lib/src/base64.dart

 // Copyright (c) 2012, the Dart project authors.  Please see the AUTHORS file
 // 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.
 
 library crypto.base64;
 
 import 'dart:convert';
 import 'dart:typed_data';
 
+/// An instance of the default implementation of [Base64Codec].
+///
+/// This provides convenient access to most common Base64 use-cases.
 const Base64Codec BASE64 = const Base64Codec();
 
+/// A mapping from ASCII character codes to their corresponding Base64 values.
+///
+/// Characters with a value of -2 are invalid. Characters with a value of -1
+/// should be ignored. The padding character, "=", is represented as 0.
 const List<int> _decodeTable = const [
   -2, -2, -2, -2, -2, -2, -2, -2, -2, -2, -1, -2, -2, -1, -2, -2,
   -2, -2, -2, -2, -2, -2, -2, -2, -2, -2, -2, -2, -2, -2, -2, -2,
   -2, -2, -2, -2, -2, -2, -2, -2, -2, -2, -2, 62, -2, 62, -2, 63,
   52, 53, 54, 55, 56, 57, 58, 59, 60, 61, -2, -2, -2,  0, -2, -2,
   -2,  0,  1,  2,  3,  4,  5,  6,  7,  8,  9, 10, 11, 12, 13, 14,
   15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, -2, -2, -2, -2, 63,
   -2, 26, 27, 28, 29, 30, 31, 32, 33, 34, 35, 36, 37, 38, 39, 40,
   41, 42, 43, 44, 45, 46, 47, 48, 49, 50, 51, -2, -2, -2, -2, -2,
   -2, -2, -2, -2, -2, -2, -2, -2, -2, -2, -2, -2, -2, -2, -2, -2,
   -2, -2, -2, -2, -2, -2, -2, -2, -2, -2, -2, -2, -2, -2, -2, -2,
   -2, -2, -2, -2, -2, -2, -2, -2, -2, -2, -2, -2, -2, -2, -2, -2,
   -2, -2, -2, -2, -2, -2, -2, -2, -2, -2, -2, -2, -2, -2, -2, -2,
   -2, -2, -2, -2, -2, -2, -2, -2, -2, -2, -2, -2, -2, -2, -2, -2,
   -2, -2, -2, -2, -2, -2, -2, -2, -2, -2, -2, -2, -2, -2, -2, -2,
   -2, -2, -2, -2, -2, -2, -2, -2, -2, -2, -2, -2, -2, -2, -2, -2,
   -2, -2, -2, -2, -2, -2, -2, -2, -2, -2, -2, -2, -2, -2, -2, -2
 ];
 
+/// A String representing a mapping from numbers between 0 and 63, inclusive, to
+/// their corresponding encoded character.
+///
+/// This is the table for URL-safe encodings.
 const String _encodeTableUrlSafe =
     "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
 
+/// A String representing a mapping from numbers between 0 and 63, inclusive, to
+/// their corresponding encoded character.
+///
+/// This is the table for URL-unsafe encodings.
 const String _encodeTable =
     "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
 
+/// The line length for Base64 strings with line separators.
 const int _LINE_LENGTH = 76;
+
+/// A carriage return.
 const int _CR = 13; // '\r'
+
+/// A line feed.
 const int _LF = 10; // '\n'
+
+/// The byte sequence representing non-URL-encoded padding.
 const List<int> _PAD_BYTES = const [61]; // '='
+
+/// The byte sequence representing URL-encoded padding.
 const List<int> _ENCODED_PAD_BYTES = const [37, 51, 68]; // '%3D'
+
+/// The string representing non-URL-encoded padding.
 const String _PAD = "=";
+
+/// The string representing URL-encoded padding.
 const String _ENCODED_PAD = "%3D";
 
+/// A codec that converts between binary data and [Base64][rfc]-encoded strings.
+///
+/// [rfc]: https://tools.ietf.org/html/rfc4648
 class Base64Codec extends Codec<List<int>, String> {
   final bool _urlSafe;
   final bool _addLineSeparator;
   final bool _encodePaddingCharacter;
 
-  /**
-   * Instantiates a new [Base64Codec].
-   *
-   * The optional [urlSafe] argument specifies if [encoder] and [encode]
-   * should generate a string, that is safe to use in an URL.
-   *
-   * If [urlSafe] is `true` (and not overriden at the method invocation)
-   * the [encoder] and [encode] use '-' instead of '+' and '_' instead of '/'.
-   *
-   * The default value of [urlSafe] is `false`.
-   *
-   * The optional [addLineSeparator] argument specifies if the [encoder] and
-   * [encode] should add line separators.
-   *
-   * If `addLineSeparator` is `true` [encode] adds an
-   * optional line separator (CR + LF) for each 76 char output.
-   *
-   * The default value of [addLineSeparator] if `false`.
-   *
-   * If [encodePaddingCharacter] is `true` `encode` converts `=` to `%3D`.
-   * The default value of [encodePaddingCharacter] is `false`.
-   */
+  /// Creates a new [Base64Codec].
+  ///
+  /// The default [BASE64] codec will be good enough for most cases. A new codec
+  /// only needs to be instantiated when you want to do multiple conversions
+  /// with the same configuration.
+  ///
+  /// If [urlSafe] is `true`, a URL-safe alphabet will be used when encoding.
+  /// Specifically, the characters `-` and `_` will be used instead of `+` and
+  /// `/`.
+  ///
+  /// If [addLineSeparator] is `true`, `\r\n` line separators will be added
+  /// every 76 characters when encoding.
+  ///
+  /// If [encodePaddingCharacter] is `true`, the padding character `=` will be
+  /// written as `%3D` when encoding.
   const Base64Codec(
       {bool urlSafe: false,
       bool addLineSeparator: false,
       bool encodePaddingCharacter: false})
       : _urlSafe = urlSafe,
         _addLineSeparator = addLineSeparator,
         _encodePaddingCharacter = encodePaddingCharacter;
 
   String get name => "base64";
 
+  /// Encodes [bytes] into a Base64 string.
+  ///
+  /// If [urlSafe] is `true`, a URL-safe alphabet will be used when encoding.
+  /// Specifically, the characters `-` and `_` will be used instead of `+` and
+  /// `/`.
+  ///
+  /// If [addLineSeparator] is `true`, `\r\n` line separators will be added
+  /// every 76 characters when encoding.
+  ///
+  /// If [encodePaddingCharacter] is `true`, the padding character `=` will be
+  /// written as `%3D` when encoding.
+  ///
+  /// Any flags passed to this method take precedence over the flags passed to
+  /// the codec itself.
   String encode(List<int> bytes,
       {bool urlSafe, bool addLineSeparator, bool encodePaddingCharacter}) {
     if (urlSafe == null) urlSafe = _urlSafe;
     if (addLineSeparator == null) addLineSeparator = _addLineSeparator;
     if (encodePaddingCharacter == null) {
       encodePaddingCharacter = _encodePaddingCharacter;
     }
     return new Base64Encoder(
         urlSafe: urlSafe,
         addLineSeparator: addLineSeparator,
         encodePaddingCharacter: encodePaddingCharacter).convert(bytes);
   }
 
   Base64Encoder get encoder => new Base64Encoder(
       urlSafe: _urlSafe,
       addLineSeparator: _addLineSeparator,
       encodePaddingCharacter: _encodePaddingCharacter);
 
   Base64Decoder get decoder => new Base64Decoder();
 }
 
-/**
- * This class encodes byte strings (lists of unsigned
- * 8-bit integers) to strings according to Base64.
- */
+/// An encoder that converts sequences of bytes to strings using [Base64][rfc].
+///
+/// [rfc]: https://tools.ietf.org/html/rfc4648
 class Base64Encoder extends Converter<List<int>, String> {
+  /// Whether this encoder generates URL-safe strings.
   final bool _urlSafe;
+
+  /// Whether this encoder adds line breaks to the output.
   final bool _addLineSeparator;
+
+  /// Whether this encoder URL-encodes trailing padding characters.
   final bool _encodePaddingCharacter;
+
+  /// The sequence of bytes to use as a padding character.
   final List<int> _pad;
 
-  /**
-   * Instantiates a new [Base64Encoder].
-   *
-   * The optional [urlSafe] argument specifies if [convert]
-   * should generate a string, that is safe to use in an URL.
-   *
-   * If it is `true` the [convert] use
-   * '-' instead of '+' and '_' instead of '/'.
-   *
-   * The default value of [urlSafe] is `false`.
-   *
-   * The optional [addLineSeparator] argument specifies if [convert]
-   * should add line separators.
-   *
-   * If it is `true` [convert] adds an optional line separator(CR + LF)
-   * for each 76 char output.
-   *
-   * The default value of [addLineSeparator] if `false`.
-   *
-   * If [encodePaddingCharacter] is `true` `encode` converts `=` to `%3D`.
-   * The default value of [encodePaddingCharacter] is `false`.
-   */
+  /// Creates a new [Base64Encoder].
+  ///
+  /// The default [BASE64.encoder] will be good enough for most cases. A new
+  /// codec only needs to be instantiated when you want to do multiple
+  /// conversions with the same configuration.
+  ///
+  /// If [urlSafe] is `true`, a URL-safe alphabet will be used. Specifically,
+  /// the characters `-` and `_` will be used instead of `+` and `/`.
+  ///
+  /// If [addLineSeparator] is `true`, `\r\n` line separators will be added
+  /// every 76 characters.
+  ///
+  /// If [encodePaddingCharacter] is `true`, the padding character `=` will be
+  /// written as `%3D`.
   const Base64Encoder(
       {bool urlSafe: false,
       bool addLineSeparator: false,
       bool encodePaddingCharacter: false})
       : _urlSafe = urlSafe,
         _addLineSeparator = addLineSeparator,
         _encodePaddingCharacter = encodePaddingCharacter,
         _pad = encodePaddingCharacter == true ? _ENCODED_PAD_BYTES : _PAD_BYTES;
 
-  /**
-   * Converts [bytes] to its Base64 representation as a string.
-   *
-   * if [start] and [end] are provided, only the sublist
-   * `bytes.sublist(start, end)` is converted.
-   */
+  /// Converts [bytes] to Base64.
+  ///
+  /// If [start] and [end] are provided, only the sublist `bytes.sublist(start,
+  /// end)` is converted.
   String convert(List<int> bytes, [int start = 0, int end]) {
     int bytes_length = bytes.length;
     RangeError.checkValidRange(start, end, bytes_length);
     if (end == null) end = bytes_length;
     int length = end - start;
     if (length == 0) {
       return "";
     }
     final String lookup = _urlSafe ? _encodeTableUrlSafe : _encodeTable;
     // Size of 24 bit chunks.
@@ skipping 57 matching lines @@
     StringConversionSink stringSink;
     if (sink is StringConversionSink) {
       stringSink = sink;
     } else {
       stringSink = new StringConversionSink.from(sink);
     }
     return new _Base64EncoderSink(stringSink, _urlSafe, _addLineSeparator);
   }
 }
 
+/// A [ChunkedConversionSink] for encoding chunks of data to Base64.
 class _Base64EncoderSink extends ChunkedConversionSink<List<int>> {
+  /// The encoder used to encode each chunk.
   final Base64Encoder _encoder;
+
+  /// The underlying sink to which to emit the encoded strings.
   final ChunkedConversionSink<String> _outSink;
+
+  /// The buffer of as-yet-unconverted bytes.
+  ///
+  /// This is used to ensure that we don't generate interstitial padding
+  /// characters.
   final List<int> _buffer = new List<int>();
+
+  /// The length of [_buffer]; that is, the number of unconverted bytes.
   int _bufferCount = 0;
 
   _Base64EncoderSink(this._outSink, urlSafe, addLineSeparator)
       : _encoder = new Base64Encoder(
             urlSafe: urlSafe, addLineSeparator: addLineSeparator);
 
   void add(List<int> chunk) {
     var nextBufferCount = (chunk.length + _bufferCount) % 3;
 
     int decodableLength = _bufferCount + chunk.length - nextBufferCount;
@@ skipping 12 matching lines @@
   }
 
   void close() {
     if (_bufferCount > 0) {
       _outSink.add(_encoder.convert(_buffer.sublist(0, _bufferCount)));
     }
     _outSink.close();
   }
 }
 
-/**
- * This class decodes strings to lists of bytes(lists of
- * unsigned 8-bit integers) according to Base64.
- */
+/// An encoder that converts [Base64][rfc] strings to sequences of bytes.
+///
+/// [rfc]: https://tools.ietf.org/html/rfc4648
 class Base64Decoder extends Converter<String, List<int>> {
-  /**
-   * Instantiates a new [Base64Decoder]
-   */
   const Base64Decoder();
 
   List<int> convert(String input) {
     int length = input.length;
     if (length == 0) {
       return new Uint8List(0);
     }
 
     int normalLength = 0;
     int i = 0;
@@ skipping 69 matching lines @@
   }
 
   _Base64DecoderSink startChunkedConversion(Sink<List<int>> sink) {
     if (sink is! ByteConversionSink) {
       sink = new ByteConversionSink.from(sink);
     }
     return new _Base64DecoderSink(sink);
   }
 }
 
+/// A [ChunkedConversionSink] for decoding chunks of Base64 strings to data.
 class _Base64DecoderSink extends ChunkedConversionSink<String> {
+  /// The encoder used to decode each chunk.
   final Base64Decoder _decoder = new Base64Decoder();
+
+  /// The underlying sink to which to emit the decoded strings.
   final ChunkedConversionSink<List<int>> _outSink;
+
+  /// The as-yet-unconverted text.
+  ///
+  /// This is used to handle a chunk stopping partway in the middle of a
+  /// URL-encoded `=` character.
   String _unconverted = "";
 
   _Base64DecoderSink(this._outSink);
 
   void add(String chunk) {
     if (chunk.isEmpty) return;
     if (_unconverted.isNotEmpty) {
       chunk = _unconverted + chunk;
     }
     chunk = chunk.replaceAll(_ENCODED_PAD, _PAD);
@@ skipping 10 matching lines @@
     }
   }
 
   void close() {
     if (_unconverted.isNotEmpty) {
       _outSink.add(_decoder.convert(_unconverted));
     }
     _outSink.close();
   }
 }