Improve comment formatting in dart-core, especially Comparable

sdk/lib/core/comparable.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.
 
 part of dart.core;
 
 /**
  * The signature of a generic comparison function.
  *
  * A comparison function represents an ordering on a type of objects.
@@ skipping 14 matching lines @@
  *
  * The [compareTo] operation defines a total ordering of objects,
  * which can be used for ordering and sorting.
  *
  * The [Comparable] interface should be used for the natural ordering of a type.
  * If a type can be ordered in more than one way,
  * and none of them is the obvious natural ordering,
  * then it might be better not to use the [Comparable] interface,
  * and to provide separate [Comparator]s instead.
  *
- * It is recommended that the order of a `Comparable` agrees
- * with its `operator==` equality (`a.compareTo(b) == 0` iff `a == b`),
+ * It is recommended that the order of a [Comparable] agrees
+ * with its operator [==] equality (`a.compareTo(b) == 0` iff `a == b`),
  * but this is not a requirement.
  * For example, [double] and [DateTime] have `compareTo` methods
- * that do not agree with `operator==`.
- * For doubles the `compareTo` method is more precise than the equality,
+ * that do not agree with operator [==].
+ * For doubles the [compareTo] method is more precise than the equality,
  * and for [DateTime] it is less precise.
  *
  * Examples:
  *
- *    (0.0).compareTo(-0.0);  // => 1
- *    0.0 == -0.0;            // => true
- *    var dt = new DateTime.now();
- *    var dt2 = dt.toUtc();
- *    dt == dt2;              // => false
- *    dt.compareTo(dt2);      // => 0
+ *      (0.0).compareTo(-0.0);  // => 1
+ *      0.0 == -0.0;            // => true
+ *      var dt = new DateTime.now();
+ *      var dt2 = dt.toUtc();
+ *      dt == dt2;              // => false
+ *      dt.compareTo(dt2);      // => 0
  *
- * The `Comparable` interface does not imply the existence
+ * The [Comparable] interface does not imply the existence
  * of the comparison operators `<`, `<=`, `>` and `>=`.
  * These should only be defined
  * if the ordering is a less-than/greater-than ordering,
  * that is, an ordering where you would naturally
  * use the words "less than" about the order of two elements.
  *
- * If the equality operator and `compareTo` disagree,
+ * If the equality operator and [compareTo] disagree,
  * the comparison operators should follow the equality operator,
- * and will likely also disagree with `compareTo`.
- * Otherwise they should match the `compareTo` method,
+ * and will likely also disagree with [compareTo].
+ * Otherwise they should match the [compareTo] method,
  * so that `a < b` iff `a.compareTo(b) < 0`.
  *
- * The `double` class defines comparison operators
+ * The [double] class defines comparison operators
  * that are compatible with equality.
- * The operators differ from [double.compareTo] on -0.0 and NaN.
+ * The operators differ from `double.compareTo` on -0.0 and NaN.
  *
- * The `DateTime` class has no comparison operators, instead it has the more
+ * The [DateTime] class has no comparison operators, instead it has the more
  * precisely named [DateTime.isBefore] and [DateTime.isAfter].
  */
 abstract class Comparable<T> {
   /**
    * Compares this object to another [Comparable]
    *
    * Returns a value like a [Comparator] when comparing `this` to [other].
-   * That is, it returns a negative integer if `this` is ordered before `other`,
-   * a positive integer if `this` is ordered after `other`,
-   * and zero if `this` and `other` are ordered together.
+   * That is, it returns a negative integer if `this` is ordered before [other],
+   * a positive integer if `this` is ordered after [other],
+   * and zero if `this` and [other] are ordered together.
    *
-   * The `other` argument must be a value that is comparable to this object.
+   * The [other] argument must be a value that is comparable to this object.
    */
   int compareTo(T other);
 
   /**
    * A [Comparator] that compares one comparable to another.
    *
    * It returns the result of `a.compareTo(b)`.
    *
    * This utility function is used as the default comparator
    * for ordering collections, for example in the [List] sort function.
    */
   static int compare(Comparable a, Comparable b) => a.compareTo(b);
 }