Adjusting matcher comments with one-line summaries

pkg/matcher/lib/src/future_matchers.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 matcher.future_matchers;
 
 import 'dart:async';
 
 import 'expect.dart';
 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.
 ///
 /// To test that a Future completes with an exception, you can use [throws] and
 /// [throwsA].
 ///
 /// [id] is an optional tag that can be used to identify the completion matcher
 /// in error messages.
 Matcher completion(matcher, [String id = '']) =>
     new _Completes(wrapMatcher(matcher), id);
@@ skipping 27 matching lines @@
 
   Description describe(Description description) {
     if (_matcher == null) {
       description.add('completes successfully');
     } else {
       description.add('completes to a value that ').addDescriptionOf(_matcher);
     }
     return description;
   }
 }