Revert "Revert "Fix dartdoc block code comments in Dart API that are broken and use [: :] delimiter…

corelib/src/expect.dart

 // Copyright (c) 2011, 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.
 
 /**
- * Expect is used for tests that do not want to make use of the 
+ * Expect is used for tests that do not want to make use of the
  * Dart unit test library - for example, the core language tests.
- * Third parties are discouraged from using this, and should use 
- * the expect() function in the unit test library instead for 
+ * Third parties are discouraged from using this, and should use
+ * the expect() function in the unit test library instead for
  * test assertions.
  */
 class Expect {
 
   /**
-   * Checks whether the expected and actual values are equal (using [:==:]).
+   * Checks whether the expected and actual values are equal (using `==`).
    */
   static void equals(var expected, var actual, [String reason = null]) {
     if (expected == actual) return;
     String msg = _getMessage(reason);
     _fail("Expect.equals(expected: <$expected>, actual: <$actual>$msg) fails.");
   }
 
   /**
    * Checks whether the actual value is a bool and its value is true.
    */
@@ skipping 25 matching lines @@
    * Checks whether [actual] is not null.
    */
   static void isNotNull(actual, [String reason = null]) {
     if (null !== actual) return;
     String msg = _getMessage(reason);
     _fail("Expect.isNotNull(actual: <$actual>$msg) fails.");
   }
 
   /**
    * Checks whether the expected and actual values are identical
-   * (using [:===:]).
+   * (using `===`).
    */
   static void identical(var expected, var actual, [String reason = null]) {
     if (expected === actual) return;
     String msg = _getMessage(reason);
     _fail("Expect.identical(expected: <$expected>, actual: <$actual>$msg) "
           "fails.");
   }
 
   // Unconditional failure.
   static void fail(String msg) {
@@ skipping 21 matching lines @@
   }
 
   static void notEquals(unexpected, actual, [String reason = null]) {
     if (unexpected != actual) return;
     String msg = _getMessage(reason);
     _fail("Expect.notEquals(unexpected: <$unexpected>, actual:<$actual>$msg) "
           "fails.");
   }
 
   /**
-   * Checks that all elements in [expected] and [actual] are equal [:==:].
-   * This is different than the typical check for identity equality [:===:]
+   * Checks that all elements in [expected] and [actual] are equal `==`.
+   * This is different than the typical check for identity equality `===`
    * used by the standard list implementation.  It should also produce nicer
-   * error messages than just calling [:Expect.equals(expected, actual):].
+   * error messages than just calling `Expect.equals(expected, actual)`.
    */
   static void listEquals(List expected, List actual, [String reason = null]) {
     String msg = _getMessage(reason);
     int n = Math.min(expected.length, actual.length);
     for (int i = 0; i < n; i++) {
       if (expected[i] != actual[i]) {
         _fail('Expect.listEquals(at index $i, '
               'expected: <${expected[i]}>, actual: <${actual[i]}>$msg) fails');
       }
     }
     // We check on length at the end in order to provide better error
     // messages when an unexpected item is inserted in a list.
     if (expected.length != actual.length) {
       _fail('Expect.listEquals(list length, '
         'expected: <${expected.length}>, actual: <${actual.length}>$msg) '
         'fails');
     }
   }
 
   /**
    * Checks that all [expected] and [actual] have the same set of keys (using
    * the semantics of [Map.containsKey] to determine what "same" means. For
-   * each key, checks that the values in both maps are equal using [:==:].
+   * each key, checks that the values in both maps are equal using `==`.
    */
   static void mapEquals(Map expected, Map actual, [String reason = null]) {
     String msg = _getMessage(reason);
 
     // Make sure all of the values are present in both and match.
     for (final key in expected.getKeys()) {
       if (!actual.containsKey(key)) {
         _fail('Expect.mapEquals(missing expected key: <$key>$msg) fails');
       }
 
@@ skipping 111 matching lines @@
     }
     _fail(sb.toString());
   }
 
   /**
    * Calls the function [f] and verifies that it throws an exception.
    * The optional [check] function can provide additional validation
    * that the correct exception is being thrown.  For example, to check
    * the type of the exception you could write this:
    *
-   * [:
-   *   Expect.throws(myThrowingFunction,
-   *                 (e) { return e is MyException})
-   * :]
+   *     Expect.throws(myThrowingFunction, (e) => e is MyException);
    */
   static void throws(void f(),
                      [_CheckExceptionFn check = null,
                       String reason = null]) {
     try {
       f();
     } catch (var e) {
       if (check !== null) {
         Expect.isTrue(check(e));
       }
@@ skipping 11 matching lines @@
   }
 }
 
 typedef bool _CheckExceptionFn(exception);
 
 class ExpectException implements Exception {
   ExpectException(this.message);
   String toString() => message;
   String message;
 }