Update documentation comments.

lib/src/hmac.dart

Index: lib/src/hmac.dart
diff --git a/lib/src/hmac.dart b/lib/src/hmac.dart
index 2e9e0ef81495267d1368809c165fa3f1ace7c081..668f40f0669dcd479b60e79418b50a586f00185a 100644
--- a/lib/src/hmac.dart
+++ b/lib/src/hmac.dart
@@ -6,35 +6,48 @@ library crypto.hmac;
 
 import 'hash.dart';
 
-/**
- * Hash-based Message Authentication Code support.
- *
- * The [add] method is used to add data to the message. The [digest] and
- * [close] methods are used to extract the message authentication code.
- */
-// TODO(floitsch): make Hash implement Sink, EventSink or similar.
+/// An implementation of [keyed-hash method authentication codes][rfc].
+///
+/// [rfc]: https://tools.ietf.org/html/rfc2104
+///
+/// HMAC allows messages to be cryptographically authenticated using any
+/// iterated cryptographic hash function.
+///
+/// The message's data is added using [add]. Once it's been fully added, the
+/// [digest] and [close] methods can be used to extract the message
+/// authentication digest.
+///
+/// If an expected authentication digest is available, the [verify] method may
+/// also be used to ensure that the message actually corresponds to that digest.
+// TODO(floitsch): make HMAC implement Sink, EventSink or similar.
 class HMAC {
+  /// The bytes from the message so far.
   final List<int> _message;
+
+  /// The hash function used to compute the authentication digest.
   Hash _hash;
+
+  /// The secret key shared by the sender and the receiver.
   List<int> _key;
+
+  /// Whether this is closed.
   bool _isClosed = false;
 
-  /**
-   * Create an [HMAC] object from a [Hash] and a key.
-   */
+  /// Create an [HMAC] object from a [Hash] and a binary key.
+  ///
+  /// The key should be a secret shared between the sender and receiver of the
+  /// message.
   HMAC(Hash this._hash, List<int> this._key) : _message = [];
 
-  /**
-   * Add a list of bytes to the message.
-   */
+  /// Adds a list of bytes to the message.
+  ///
+  /// If [this] has already been closed, throws a [StateError].
   void add(List<int> data) {
     if (_isClosed) throw new StateError("HMAC is closed");
     _message.addAll(data);
   }
 
-  /**
-   * Extract the message digest as a list of bytes without closing [this].
-   */
+  /// Returns the digest of the message so far, as a list of bytes.
   List<int> get digest {
     var blockSize = _hash.blockSize;
 
@@ -79,25 +92,22 @@ class HMAC {
     return _hash.close();
   }
 
-  /**
-   * Perform the actual computation and extract the message digest
-   * as a list of bytes.
-   */
+  /// Closes [this] and returns the digest of the message as a list of bytes.
+  ///
+  /// Once closed, [add] may no longer be called.
   List<int> close() {
     _isClosed = true;
     return digest;
   }
 
-  /**
-   * Verify that the HMAC computed for the data so far matches the
-   * given message digest.
-   *
-   * This method should be used instead of memcmp-style comparisons
-   * to avoid leaking information via timing.
-   *
-   * Throws an exception if the given digest does not have the same
-   * size as the digest computed by this HMAC instance.
-   */
+  /// Returns whether the digest computed for the data so far matches the given
+  /// [digest].
+  ///
+  /// This method should be used instead of iterative comparisons to avoid
+  /// leaking information via timing.
+  ///
+  /// Throws an [ArgumentError] if the given digest does not have the same size
+  /// as the digest computed by [this].
   bool verify(List<int> digest) {
     var computedDigest = this.digest;
     if (digest.length != computedDigest.length) {