diff --git a/lib/src/core_matchers.dart b/lib/src/core_matchers.dart
index 8de3a01..c3c996d 100644
--- a/lib/src/core_matchers.dart
+++ b/lib/src/core_matchers.dart
@@ -389,6 +389,7 @@
 }
 
 /// A matcher that matches a function call against no exception.
+///
 /// The function will be called once. Any exceptions will be silently swallowed.
 /// The value passed to expect() should be a reference to the function.
 /// Note that the function cannot take arguments; to handle this
@@ -502,12 +503,13 @@
   }
 }
 
-/// Returns a matcher that matches if the match argument contains
-/// the expected value. For [String]s this means substring matching;
+/// Returns a matcher that matches if the match argument contains the expected
+/// value.
+///
+/// For [String]s this means substring matching;
 /// for [Map]s it means the map has the key, and for [Iterable]s
-/// (including [Iterable]s) it means the iterable has a matching
-/// element. In the case of iterables, [expected] can itself be a
-/// matcher.
+/// it means the iterable has a matching element. In the case of iterables,
+/// [expected] can itself be a matcher.
 Matcher contains(expected) => new _Contains(expected);
 
 class _Contains extends Matcher {
@@ -569,7 +571,9 @@
 }
 
 /// Returns a matcher that uses an arbitrary function that returns
-/// true or false for the actual value. For example:
+/// true or false for the actual value.
+///
+/// For example:
 ///
 ///     expect(v, predicate((x) => ((x % 2) == 0), "is even"))
 Matcher predicate(bool f(value), [String description = 'satisfies function']) =>
diff --git a/lib/src/expect.dart b/lib/src/expect.dart
index bd54747..1bfa36e 100644
--- a/lib/src/expect.dart
+++ b/lib/src/expect.dart
@@ -45,6 +45,8 @@
 typedef String ErrorFormatter(actual, Matcher matcher, String reason,
   Map matchState, bool verbose);
 
+/// This Function is used by certain Matchers to catch certain exceptions.
+///
 /// Some matchers, like those for Futures and exception testing,
 /// can fail in asynchronous sections, and throw exceptions.
 /// A user of this library will typically want to catch and handle
@@ -54,9 +56,10 @@
 /// to be `expectAsync`. By default this is an identity function.
 Function wrapAsync = (Function f, [id]) => f;
 
-/// This is the main assertion function. It asserts that [actual]
-/// matches the [matcher]. [reason] is optional and is typically not
-/// supplied, as a reason is generated from the matcher; if [reason]
+/// Assert that [actual] matches [matcher].
+///
+/// This is the main assertion function. [reason] is optional and is typically
+/// not supplied, as a reason is generated from the matcher; if [reason]
 /// is included it is appended to the reason generated by the matcher.
 ///
 /// [matcher] can be a value in which case it will be wrapped in an
@@ -119,7 +122,8 @@
   }
 }
 
-/// Changes or resets to the default the failure handler for expect()
+/// Changes the default failure handler for [expect].
+///
 /// [handler] is a reference to the new handler; if this is omitted
 /// or null then the failure handler is reset to the default, which
 /// throws [TestFailure]s on [expect] assertion failures.
@@ -159,7 +163,8 @@
   return description.toString();
 }
 
-/// Changes or resets to default the failure message formatter for expect().
+/// Changes the failure message formatter for expect().
+///
 /// [formatter] is a reference to the new formatter; if this is omitted or
 /// null then the failure formatter is reset to the default. The new
 /// formatter is returned; this allows custom expect handlers to easily
diff --git a/lib/src/future_matchers.dart b/lib/src/future_matchers.dart
index f1d7cb8..615b588 100644
--- a/lib/src/future_matchers.dart
+++ b/lib/src/future_matchers.dart
@@ -10,17 +10,20 @@
 import 'interfaces.dart';
 import 'util.dart';
 
-/// Matches a [Future] that completes successfully with a value. Note that this
-/// creates an asynchronous expectation. The call to `expect()` that includes
-/// this will return immediately and execution will continue. Later, when the
-/// future completes, the actual expectation will run.
+/// Matches a [Future] that completes successfully with a value.
+///
+/// Note that this creates an asynchronous expectation. The call to `expect()`
+/// that includes this will return immediately and execution will continue.
+/// Later, when the future completes, the actual expectation will run.
 ///
 /// To test that a Future completes with an exception, you can use [throws] and
 /// [throwsA].
 final Matcher completes = const _Completes(null, '');
 
 /// Matches a [Future] that completes succesfully with a value that matches
-/// [matcher]. Note that this creates an asynchronous expectation. The call to
+/// [matcher].
+///
+/// Note that this creates an asynchronous expectation. The call to
 /// `expect()` that includes this will return immediately and execution will
 /// continue. Later, when the future completes, the actual expectation will run.
 ///
diff --git a/lib/src/iterable_matchers.dart b/lib/src/iterable_matchers.dart
index eeea0ee..60ef32d 100644
--- a/lib/src/iterable_matchers.dart
+++ b/lib/src/iterable_matchers.dart
@@ -78,9 +78,9 @@
 }
 
 /// Returns a matcher which matches [Iterable]s that have the same
-/// length and the same elements as [expected], and in the same order.
-/// This is equivalent to equals but does not recurse.
-
+/// length and the same elements as [expected], in the same order.
+///
+/// This is equivalent to [equals] but does not recurse.
 Matcher orderedEquals(Iterable expected) => new _OrderedEquals(expected);
 
 class _OrderedEquals extends Matcher {
@@ -108,10 +108,10 @@
   }
 }
 
-/// Returns a matcher which matches [Iterable]s that have the same
-/// length and the same elements as [expected], but not necessarily in
-/// the same order. Note that this is O(n^2) so should only be used on
-/// small objects.
+/// Returns a matcher which matches [Iterable]s that have the same length and
+/// the same elements as [expected], but not necessarily in the same order.
+///
+/// Note that this is O(n^2) so should only be used on small objects.
 Matcher unorderedEquals(Iterable expected) => new _UnorderedEquals(expected);
 
 class _UnorderedEquals extends _UnorderedMatches {
@@ -209,10 +209,11 @@
       mismatchDescription.add(_test(item));
 }
 
-/// A pairwise matcher for iterable. You can pass an arbitrary [comparator]
-/// function that takes an expected and actual argument which will be applied
-/// to each pair in order. [description]  should be a meaningful name for
-/// the comparator.
+/// A pairwise matcher for [Iterable]s.
+///
+/// The [comparator] function, taking an expected and an actual argument, and
+/// returning whether they match, will be applied to each pair in order.
+/// [description] should be a meaningful name for the comparator.
 Matcher pairwiseCompare(Iterable expected, bool comparator(a, b),
     String description) =>
         new _PairwiseCompare(expected, comparator, description);
diff --git a/lib/src/numeric_matchers.dart b/lib/src/numeric_matchers.dart
index ae0b0ad..03134dd 100644
--- a/lib/src/numeric_matchers.dart
+++ b/lib/src/numeric_matchers.dart
@@ -111,7 +111,9 @@
 }
 
 /// Returns a matcher which matches if the match argument is within [delta]
-/// of some [value]; i.e. if the match argument is greater than
+/// of some [value].
+///
+/// In other words, this matches if the match argument is greater than
 /// than or equal [value]-[delta] and less than or equal to [value]+[delta].
 Matcher closeTo(num value, num delta) => new _IsCloseTo(value, delta);
 
diff --git a/lib/src/operator_matchers.dart b/lib/src/operator_matchers.dart
index a6d23c2..4661b7d 100644
--- a/lib/src/operator_matchers.dart
+++ b/lib/src/operator_matchers.dart
@@ -22,9 +22,10 @@
 }
 
 /// This returns a matcher that matches if all of the matchers passed as
-/// arguments (up to 7) match. Instead of passing the matchers separately
-/// they can be passed as a single List argument.
-/// Any argument that is not a matcher is implicitly wrapped in a
+/// arguments (up to 7) match.
+///
+/// Instead of passing the matchers separately they can be passed as a single
+/// List argument. Any argument that is not a matcher is implicitly wrapped in a
 /// Matcher to check for equality.
 Matcher allOf(arg0,
              [arg1 = null,
@@ -63,8 +64,9 @@
       description.addAll('(', ' and ', ')', _matchers);
 }
 
-/// Matches if any of the given matchers evaluate to true. The
-/// arguments can be a set of matchers as separate parameters
+/// Matches if any of the given matchers evaluate to true.
+///
+/// The arguments can be a set of matchers as separate parameters
 /// (up to 7), or a List of matchers.
 ///
 /// The matchers are evaluated from left to right using short-circuit
@@ -72,7 +74,6 @@
 ///
 /// Any argument that is not a matcher is implicitly wrapped in a
 /// Matcher to check for equality.
-
 Matcher anyOf(arg0,
                [arg1 = null,
                 arg2 = null,
diff --git a/lib/src/string_matchers.dart b/lib/src/string_matchers.dart
index c498446..616a4b6 100644
--- a/lib/src/string_matchers.dart
+++ b/lib/src/string_matchers.dart
@@ -26,13 +26,24 @@
 }
 
 /// Returns a matcher which matches if the match argument is a string and
-/// is equal to [value] when compared with all runs of whitespace
-/// collapsed to single spaces and leading and trailing whitespace removed.
+/// is equal to [value], ignoring whitespace.
 ///
-/// For example, `equalsIgnoringCase("hello world")` will match
-/// "hello   world", "  hello world" and "hello world  ".
-Matcher equalsIgnoringWhitespace(String string) =>
-    new _IsEqualIgnoringWhitespace(string);
+/// In this matcher, "ignoring whitespace" means comparing with all runs of
+/// whitespace collapsed to single space characters and leading and trailing
+/// whitespace removed.
+///
+/// For example, the following will all match successfully:
+///
+///     expect("hello   world", equalsIgnoringCase("hello world"));
+///     expect("  hello world", equalsIgnoringCase("hello world"));
+///     expect("hello world  ", equalsIgnoringCase("hello world"));
+///
+/// The following will not match:
+///
+///     expect("helloworld", equalsIgnoringCase("hello world"));
+///     expect("he llo world", equalsIgnoringCase("hello world"));
+Matcher equalsIgnoringWhitespace(String value) =>
+    new _IsEqualIgnoringWhitespace(value);
 
 class _IsEqualIgnoringWhitespace extends _StringMatcher {
   final String _value;
@@ -125,9 +136,10 @@
 }
 
 /// Returns a matcher that matches if the match argument is a string and
-/// matches the regular expression given by [re]. [re] can be a [RegExp]
-/// instance or a [String]; in the latter case it will be used to create
-/// a RegExp instance.
+/// matches the regular expression given by [re].
+///
+/// [re] can be a [RegExp] instance or a [String]; in the latter case it will be
+/// used to create a RegExp instance.
 Matcher matches(re) => new _MatchesRegExp(re);
 
 class _MatchesRegExp extends _StringMatcher {
diff --git a/lib/src/util.dart b/lib/src/util.dart
index 08cba77..3ecc47c 100644
--- a/lib/src/util.dart
+++ b/lib/src/util.dart
@@ -15,7 +15,8 @@
   matchState.addAll(values);
 }
 
-/// Takes an argument and returns an equivalent matcher.
+/// Takes an argument and returns an equivalent [Matcher].
+///
 /// If the argument is already a matcher this does nothing,
 /// else if the argument is a function, it generates a predicate
 /// function matcher, else it generates an equals matcher.