Improve comment formatting in dart-core, especially Comparable

sdk/lib/core/set.dart

Index: sdk/lib/core/set.dart
diff --git a/sdk/lib/core/set.dart b/sdk/lib/core/set.dart
index 059f320db23ab06a608fb189012bc1fbf2727bc2..f5b81b9e53b9a733aa0701ab2e706ca29fed99ff 100644
--- a/sdk/lib/core/set.dart
+++ b/sdk/lib/core/set.dart
@@ -13,8 +13,9 @@ part of dart.core;
  * Set implementations may consider some elements indistinguishable. These
  * elements are treated as being the same for any operation on the set.
  *
- * The default `Set` implementation, [LinkedHashSet], considers objects
- * indistinguishable if they are equal with regard to [Object.operator==].
+ * The default [Set] implementation, [LinkedHashSet], considers objects
+ * indistinguishable if they are equal with regard to 
+ * operator [dart-core.Object.==].
  *
  * Sets may be either ordered or unordered. [HashSet] is unordered and
  * doesn't guarantee anything about the order that elements are accessed in by
@@ -23,23 +24,23 @@ part of dart.core;
  * It is generally not allowed to modify the set (add or remove elements) while
  * an operation on the set is being performed, for example during a call to
  * [forEach] or [containsAll]. Nor is it allowed to modify the set while
- * iterating either the set itself or any `Iterable` that is backed by the set,
+ * iterating either the set itself or any [Iterable] that is backed by the set,
  * such as the ones returned by methods like [where] and [map].
  */
 abstract class Set<E> extends IterableBase<E> implements EfficientLength {
   /**
    * Creates an empty [Set].
    *
-   * The created `Set` is a [LinkedHashSet]. As such, it considers elements that
-   * are equal (using `==`) to be indistinguishable, and requires them to
-   * have a compatible [Object.hashCode] implementation.
+   * The created [Set] is a [LinkedHashSet]. As such, it considers elements that
+   * are equal (using [==]) to be indistinguishable, and requires them to
+   * have a compatible [dart-core.Object.hashCode] implementation.

[Emily Fortuna, 2014/01/09 18:21:57]

shouldn't need the dart-core....

[Alan Knight, 2014/01/09 18:47:28]

Weird. For some reason it had seemed like I needed that, but looking again it
doesn't even work. Removed here and throughout.

    */
   factory Set() = LinkedHashSet<E>;
 
   /**
    * Creates an empty identity [Set].
    *
-   * The created `Set` is a [LinkedHashSet] that uses identity as equality
+   * The created [Set] is a [LinkedHashSet] that uses identity as equality
    * relation.
    */
   factory Set.identity() = LinkedHashSet<E>.identity;
@@ -47,9 +48,9 @@ abstract class Set<E> extends IterableBase<E> implements EfficientLength {
   /**
    * Creates a [Set] that contains all elements of [other].
    *
-   * The created `Set` is a [LinkedHashSet]. As such, it considers elements that
-   * are equal (using `==`) to be undistinguishable, and requires them to
-   * have a compatible [Object.hashCode] implementation.
+   * The created [Set] is a [LinkedHashSet]. As such, it considers elements that
+   * are equal (using [==]) to be undistinguishable, and requires them to
+   * have a compatible [dart-core.Object.hashCode] implementation.
    */
   factory Set.from(Iterable<E> other) = LinkedHashSet<E>.from;
 
@@ -121,15 +122,15 @@ abstract class Set<E> extends IterableBase<E> implements EfficientLength {
   /**
    * Returns a new set which is the intersection between this set and [other].
    *
-   * That is, the returned set contains all the elements of this `Set` that
-   * are also elements of `other` according to `other.contains`.
+   * That is, the returned set contains all the elements of this [Set] that
+   * are also elements of [other] according to `other.contains`.
    */
   Set<E> intersection(Set<Object> other);
 
   /**
    * Returns a new set which contains all the elements of this set and [other].
    *
-   * That is, the returned set contains all the elements of this `Set` and
+   * That is, the returned set contains all the elements of this [Set] and
    * all the elements of [other].
    */
   Set<E> union(Set<E> other);
@@ -137,7 +138,7 @@ abstract class Set<E> extends IterableBase<E> implements EfficientLength {
   /**
    * Returns a new set with the the elements of this that are not in [other].
    *
-   * That is, the returned set contains all the elements of this `Set` that
+   * That is, the returned set contains all the elements of this [Set] that
    * are not elements of [other] according to `other.contains`.
    */
   Set<E> difference(Set<E> other);