* - * The ordering imposed by a comparator c on a set of elements - * S is said to be consistent with equals if and only if - * c.compare(e1, e2)==0 has the same boolean value as - * e1.equals(e2) for every e1 and e2 in - * S.
+ * The ordering imposed by a comparator {@code c} on a set of elements + * {@code S} is said to be consistent with equals if and only if + * {@code c.compare(e1, e2)==0} has the same boolean value as + * {@code e1.equals(e2)} for every {@code e1} and {@code e2} in + * {@code S}.
* * Caution should be exercised when using a comparator capable of imposing an * ordering inconsistent with equals to order a sorted set (or sorted map). - * Suppose a sorted set (or sorted map) with an explicit comparator c - * is used with elements (or keys) drawn from a set S. If the - * ordering imposed by c on S is inconsistent with equals, + * Suppose a sorted set (or sorted map) with an explicit comparator {@code c} + * is used with elements (or keys) drawn from a set {@code S}. If the + * ordering imposed by {@code c} on {@code S} is inconsistent with equals, * the sorted set (or sorted map) will behave "strangely." In particular the * sorted set (or sorted map) will violate the general contract for set (or - * map), which is defined in terms of equals.
+ * map), which is defined in terms of {@code equals}.
* * For example, suppose one adds two elements {@code a} and {@code b} such that * {@code (a.equals(b) && c.compare(a, b) != 0)} @@ -67,23 +67,23 @@ * {@link Set#add Set.add} method.
* * Note: It is generally a good idea for comparators to also implement - * java.io.Serializable, as they may be used as ordering methods in + * {@code java.io.Serializable}, as they may be used as ordering methods in * serializable data structures (like {@link TreeSet}, {@link TreeMap}). In * order for the data structure to serialize successfully, the comparator (if - * provided) must implement Serializable.
+ * provided) must implement {@code Serializable}.
* * For the mathematically inclined, the relation that defines the - * imposed ordering that a given comparator c imposes on a - * given set of objects S is:
+ * imposed ordering that a given comparator {@code c} imposes on a
+ * given set of objects {@code S} is:
* {(x, y) such that c.compare(x, y) <= 0}.
* The quotient for this total order is:
* {(x, y) such that c.compare(x, y) == 0}.
*
*
- * It follows immediately from the contract for compare that the
- * quotient is an equivalence relation on S, and that the
- * imposed ordering is a total order on S. When we say that
- * the ordering imposed by c on S is consistent with
+ * It follows immediately from the contract for {@code compare} that the
+ * quotient is an equivalence relation on {@code S}, and that the
+ * imposed ordering is a total order on {@code S}. When we say that
+ * the ordering imposed by {@code c} on {@code S} is consistent with
* equals, we mean that the quotient for the ordering is the equivalence
* relation defined by the objects' {@link Object#equals(Object)
* equals(Object)} method(s):
@@ -113,26 +113,26 @@
* to, or greater than the second.
*
* In the foregoing description, the notation
- * sgn(expression) designates the mathematical
- * signum function, which is defined to return one of -1,
- * 0, or 1 according to whether the value of
+ * {@code sgn(}expression{@code )} designates the mathematical
+ * signum function, which is defined to return one of {@code -1},
+ * {@code 0}, or {@code 1} according to whether the value of
* expression is negative, zero or positive.
*
- * The implementor must ensure that sgn(compare(x, y)) ==
- * -sgn(compare(y, x)) for all x and y. (This
- * implies that compare(x, y) must throw an exception if and only
- * if compare(y, x) throws an exception.)
+ * The implementor must ensure that {@code sgn(compare(x, y)) ==
+ * -sgn(compare(y, x))} for all {@code x} and {@code y}. (This
+ * implies that {@code compare(x, y)} must throw an exception if and only
+ * if {@code compare(y, x)} throws an exception.)
*
* The implementor must also ensure that the relation is transitive:
- * ((compare(x, y)>0) && (compare(y, z)>0)) implies
- * compare(x, z)>0.
+ * {@code ((compare(x, y)>0) && (compare(y, z)>0))} implies
+ * {@code compare(x, z)>0}.
*
- * Finally, the implementor must ensure that compare(x, y)==0
- * implies that sgn(compare(x, z))==sgn(compare(y, z)) for all
- * z.
+ * Finally, the implementor must ensure that {@code compare(x, y)==0}
+ * implies that {@code sgn(compare(x, z))==sgn(compare(y, z))} for all
+ * {@code z}.
*
* It is generally the case, but not strictly required that
- * (compare(x, y)==0) == (x.equals(y)). Generally speaking,
+ * {@code (compare(x, y)==0) == (x.equals(y))}. Generally speaking,
* any comparator that violates this condition should clearly indicate
* this fact. The recommended language is "Note: this comparator
* imposes orderings that are inconsistent with equals."
@@ -153,19 +153,19 @@
* Indicates whether some other object is "equal to" this
* comparator. This method must obey the general contract of
* {@link Object#equals(Object)}. Additionally, this method can return
- * true only if the specified object is also a comparator
+ * {@code true} only if the specified object is also a comparator
* and it imposes the same ordering as this comparator. Thus,
- * comp1.equals(comp2) implies that sgn(comp1.compare(o1,
- * o2))==sgn(comp2.compare(o1, o2)) for every object reference
- * o1 and o2.
+ * {@code comp1.equals(comp2)} implies that {@code sgn(comp1.compare(o1,
+ * o2))==sgn(comp2.compare(o1, o2))} for every object reference
+ * {@code o1} and {@code o2}.
*
* Note that it is always safe not to override
- * Object.equals(Object). However, overriding this method may,
+ * {@code Object.equals(Object)}. However, overriding this method may,
* in some cases, improve performance by allowing programs to determine
* that two distinct comparators impose the same order.
*
* @param obj the reference object with which to compare.
- * @return true only if the specified object is also
+ * @return {@code true} only if the specified object is also
* a comparator and it imposes the same ordering as this
* comparator.
* @see Object#equals(Object)