_[Original issue](https://code.google.com/p/guava-libraries/issues/detail?id=1813) created by **j...@nwsnet.de** on 2014-07-23 at 03:21 PM_

---

I didn't find information on the immutability of `Range`&nbsp;instances in the JavaDocs [1]; only the wiki page [2] explicitly states it.

I suggest documenting the immutability directly in the JavaDocs, and thus in the implementation itself.

[1] https://google.github.io/guava/apidocs/com/google/common/collect/Range.html
[2] https://code.google.com/p/guava-libraries/wiki/RangesExplained

(Slightly unrelated: The comments disappeared from the wiki, especially helpful ones which I remembered to be on the page on ranges are gone. I'd like to state that I don't welcome that change.)

}
  /**
   * Returns the minimal range that {@linkplain #encloses encloses} both this range and {@code
   * other}. For example, the span of {@code [1..3]} and {@code (5..7)} is {@code [1..7)}.
   *
   * <p><i>If</i> the input ranges are {@linkplain #isConnected connected}, the returned range can
   * also be called their <i>union</i>. If they are not, note that the span might contain values
   * that are not contained in either input range.
   *
   * <p>Like {@link #intersection(Range) intersection}, this operation is commutative, associative
   * and idempotent. Unlike it, it is always well-defined for any two input ranges.
   */
  public Range<C> span(Range<C> other) {
    int lowerCmp = lowerBound.compareTo(other.lowerBound);
    int upperCmp = upperBound.compareTo(other.upperBound);
    if (lowerCmp <= 0 && upperCmp >= 0) {
      return this;
    } else if (lowerCmp >= 0 && upperCmp <= 0) {
      return other;
    } else {
      Cut<C> newLower = (lowerCmp <= 0) ? lowerBound : other.lowerBound;
      Cut<C> newUpper = (upperCmp >= 0) ? upperBound : other.upperBound;
      return create(newLower, newUpper);
    }
  }
  /**
   * Returns the canonical form of this range in the given domain. The canonical form has the
   * following properties:
   *
   * <ul>