_[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.)

} else if (lowerCmp <= 0 && upperCmp >= 0) {
      return connectedRange;
    } else {
      Cut<C> newLower = (lowerCmp >= 0) ? lowerBound : connectedRange.lowerBound;
      Cut<C> newUpper = (upperCmp <= 0) ? upperBound : connectedRange.upperBound;
      return create(newLower, newUpper);
    }
  }
  /**
   * Returns the maximal range lying between this range and {@code otherRange}, if such a range
   * exists. The resulting range may be empty if the two ranges are adjacent but non-overlapping.
   *
   * <p>For example, the gap of {@code [1..5]} and {@code (7..10)} is {@code (5..7]}. The resulting
   * range may be empty; for example, the gap between {@code [1..5)} {@code [5..7)} yields the empty
   * range {@code [5..5)}.
   *
   * <p>The gap exists if and only if the two ranges are either disconnected or immediately adjacent
   * (any intersection must be an empty range).
   *
   * <p>The gap operation is commutative.
   *
   * @throws IllegalArgumentException if this range and {@code otherRange} have a nonempty
   *     intersection
   * @since 27.0
   */
  public Range<C> gap(Range<C> otherRange) {
    boolean isThisFirst = this.lowerBound.compareTo(otherRange.lowerBound) < 0;
    Range<C> firstRange = isThisFirst ? this : otherRange;
    Range<C> secondRange = isThisFirst ? otherRange : this;
    return create(firstRange.upperBound, secondRange.lowerBound);