--- old/src/java.base/share/classes/java/util/Collection.java	2019-05-13 17:16:10.000000000 -0700
+++ new/src/java.base/share/classes/java/util/Collection.java	2019-05-13 17:16:10.000000000 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1997, 2018, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1997, 2019, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -101,6 +101,16 @@
  * the specified behavior of underlying {@link Object} methods wherever the
  * implementor deems it appropriate.
  *
+ * <p>Some collection interfaces and implementations may specify membership
+ * semantics that are not defined in terms of the {@code equals} method. For
+ * example, the {@link SortedSet#contains(Object) SortedSet.contains} method
+ * is defined in terms of a comparison method provided at construction time
+ * instead of the {@code equals} method. Such collections are well-defined,
+ * although their behavior may be counterintuitive when mixed with collections
+ * that use different membership semantics. For operations that may involve the
+ * membership semantics of more than one collection, it is specified which
+ * collection's membership semantics the operation uses.
+ *
  * <p>Some collection operations which perform recursive traversal of the
  * collection may fail with an exception for self-referential instances where
  * the collection directly or indirectly contains itself. This includes the
@@ -445,7 +455,13 @@
 
     /**
      * Returns {@code true} if this collection contains all of the elements
-     * in the specified collection.
+     * in the specified collection. This operation uses the membership semantics
+     * of this collection.
+     *
+     * @implNote
+     * Most implementations will call this collection's {@code contains}
+     * method repeatedly. This may result in performance problems if the
+     * {@code contains} method has linear or worse performance.
      *
      * @param  c collection to be checked for containment in this collection
      * @return {@code true} if this collection contains all of the elements
@@ -493,8 +509,14 @@
      * Removes all of this collection's elements that are also contained in the
      * specified collection (optional operation).  After this call returns,
      * this collection will contain no elements in common with the specified
+     * collection. This operation uses the membership semantics of the specified
      * collection.
      *
+     * @implNote
+     * Most implementations will call the specified collection's {@code contains}
+     * method repeatedly. This may result in performance problems if the specified
+     * collection's {@code contains} operation has linear or worse performance.
+     *
      * @param c collection containing elements to be removed from this collection
      * @return {@code true} if this collection changed as a result of the
      *         call
@@ -553,8 +575,14 @@
      * Retains only the elements in this collection that are contained in the
      * specified collection (optional operation).  In other words, removes from
      * this collection all of its elements that are not contained in the
+     * specified collection. This operation uses the membership semantics of the
      * specified collection.
      *
+     * @implNote
+     * Most implementations will call the specified collection's {@code contains}
+     * method repeatedly. This may result in performance problems if the specified
+     * collection's {@code contains} operation has linear or worse performance.
+     *
      * @param c collection containing elements to be retained in this collection
      * @return {@code true} if this collection changed as a result of the call
      * @throws UnsupportedOperationException if the {@code retainAll} operation