diff --git a/lib/src/interfaces.dart b/lib/src/interfaces.dart
index 0ef8248..1f39fa4 100644
--- a/lib/src/interfaces.dart
+++ b/lib/src/interfaces.dart
@@ -2,14 +2,12 @@
 // 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.
 
-// To decouple the reporting of errors, and allow for extensibility of
-// matchers, we make use of some interfaces.
-
-/// Matchers build up their error messages by appending to
-/// Description objects. This interface is implemented by
-/// StringDescription. This interface is unlikely to need
-/// other implementations, but could be useful to replace in
-/// some cases - e.g. language conversion.
+/// Matchers build up their error messages by appending to Description objects.
+///
+/// This interface is implemented by StringDescription.
+///
+/// This interface is unlikely to need other implementations, but could be
+/// useful to replace in some cases - e.g. language conversion.
 abstract class Description {
   int get length;
 
@@ -27,27 +25,32 @@
   Description addAll(String start, String separator, String end, Iterable list);
 }
 
-/// The base Matcher class has a generic implementation of [describeMismatch]
-/// so this does not need to be provided unless a more clear description is
-/// required. The other two methods ([matches] and [describe])
-/// must always be provided as they are highly matcher-specific.
+/// The base class for all matchers.
+///
+/// [matches] and [describe] must be implemented by subclasses.
+///
+/// Subclasses can override [describeMismatch] if a more specific description is
+/// required when the matcher fails.
 abstract class Matcher {
   const Matcher();
 
-  /// This does the matching of the actual vs expected values.
+  /// Does the matching of the actual vs expected values.
+  ///
   /// [item] is the actual value. [matchState] can be supplied
   /// and may be used to add details about the mismatch that are too
   /// costly to determine in [describeMismatch].
   bool matches(item, Map matchState);
 
-  /// This builds a textual description of the matcher.
+  /// Builds a textual description of the matcher.
   Description describe(Description description);
 
-  /// This builds a textual description of a specific mismatch. [item]
-  /// is the value that was tested by [matches]; [matchState] is
+  /// Builds a textual description of a specific mismatch.
+  ///
+  /// [item] is the value that was tested by [matches]; [matchState] is
   /// the [Map] that was passed to and supplemented by [matches]
   /// with additional information about the mismatch, and [mismatchDescription]
   /// is the [Description] that is being built to describe the mismatch.
+  ///
   /// A few matchers make use of the [verbose] flag to provide detailed
   /// information that is not typically included but can be of help in
   /// diagnosing failures, such as stack traces.