--- old/src/java.base/share/classes/java/util/Set.java	2019-05-13 17:16:16.000000000 -0700
+++ new/src/java.base/share/classes/java/util/Set.java	2019-05-13 17:16:16.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
@@ -280,9 +280,13 @@
     // Bulk Operations
 
     /**
-     * Returns {@code true} if this set contains all of the elements of the
-     * specified collection.  If the specified collection is also a set, this
-     * method returns {@code true} if it is a <i>subset</i> of this set.
+     * Returns {@code true} if this set contains all of the elements
+     * in the specified collection. This operation uses the membership
+     * semantics of this set. If the specified collection is also a set,
+     * this method returns {@code true} if it is a <i>subset</i> of this set.
+     *
+     * @implNote
+     * {@inheritDoc}
      *
      * @param  c collection to be checked for containment in this set
      * @return {@code true} if this set contains all of the elements of the
@@ -328,10 +332,14 @@
      * Retains only the elements in this set that are contained in the
      * specified collection (optional operation).  In other words, removes
      * from this set all of its elements that are not contained in the
-     * specified collection.  If the specified collection is also a set, this
+     * specified collection. This operation uses the membership semantics of the
+     * specified collection. If the specified collection is also a set, this
      * operation effectively modifies this set so that its value is the
      * <i>intersection</i> of the two sets.
      *
+     * @implNote
+     * {@inheritDoc}
+     *
      * @param  c collection containing elements to be retained in this set
      * @return {@code true} if this set changed as a result of the call
      * @throws UnsupportedOperationException if the {@code retainAll} operation
@@ -349,10 +357,15 @@
 
     /**
      * Removes from this set all of its elements that are contained in the
-     * specified collection (optional operation).  If the specified
-     * collection is also a set, this operation effectively modifies this
-     * set so that its value is the <i>asymmetric set difference</i> of
-     * the two sets.
+     * specified collection (optional operation). After this call returns,
+     * this set will contain no elements in common with the specified
+     * collection. This operation uses the membership semantics of the specified
+     * collection. If the specified collection is also a set, this operation
+     * effectively modifies this set so that its value is the <i>asymmetric
+     * set difference</i> of the two sets.
+     *
+     * @implNote
+     * {@inheritDoc}
      *
      * @param  c collection containing elements to be removed from this set
      * @return {@code true} if this set changed as a result of the call
@@ -383,13 +396,18 @@
     // Comparison and hashing
 
     /**
-     * Compares the specified object with this set for equality.  Returns
+     * Compares the specified object with this set for equality. Returns
      * {@code true} if the specified object is also a set, the two sets
      * have the same size, and every member of the specified set is
-     * contained in this set (or equivalently, every member of this set is
-     * contained in the specified set).  This definition ensures that the
-     * equals method works properly across different implementations of the
-     * set interface.
+     * contained in this set. This operation uses the membership semantics
+     * of this set. This definition ensures that the {@code equals} method
+     * works properly across different implementations of the
+     * {@code Set} interface.
+     *
+     * @implNote
+     * Most implementations will call this set's {@code contains}
+     * method repeatedly. This may result in performance problems if the
+     * {@code contains} method has linear or worse performance.
      *
      * @param o object to be compared for equality with this set
      * @return {@code true} if the specified object is equal to this set