Improve comment formatting in dart-core, especially Comparable

sdk/lib/core/comparable.dart

Index: sdk/lib/core/comparable.dart
diff --git a/sdk/lib/core/comparable.dart b/sdk/lib/core/comparable.dart
index 1b770af9ff276054821da34e2df398dcda2f14da..7a22948a080fabb5649088b32bcfc4499fcb89c2 100644
--- a/sdk/lib/core/comparable.dart
+++ b/sdk/lib/core/comparable.dart
@@ -32,41 +32,41 @@ typedef int Comparator<T>(T a, T b);
  * 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> {
@@ -74,11 +74,11 @@ 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);