diff --git a/core/java/android/net/NetworkCapabilities.java b/core/java/android/net/NetworkCapabilities.java
index ff5714b382..f7cdcdd2f2 100644
--- a/core/java/android/net/NetworkCapabilities.java
+++ b/core/java/android/net/NetworkCapabilities.java
@@ -382,7 +382,7 @@ public final class NetworkCapabilities implements Parcelable {
     /**
      * Removes (if found) the given capability from this {@code NetworkCapability} instance.
      * <p>
-     * Note that this method removes capabilities that was added via {@link #addCapability(int)},
+     * Note that this method removes capabilities that were added via {@link #addCapability(int)},
      * {@link #addUnwantedCapability(int)} or {@link #setCapabilities(int[], int[])} .
      *
      * @param capability the capability to be removed.
@@ -471,6 +471,7 @@ public final class NetworkCapabilities implements Parcelable {
                 && ((mUnwantedNetworkCapabilities & (1 << capability)) != 0);
     }
 
+    /** Note this method may result in having the same capability in wanted and unwanted lists. */
     private void combineNetCapabilities(NetworkCapabilities nc) {
         this.mNetworkCapabilities |= nc.mNetworkCapabilities;
         this.mUnwantedNetworkCapabilities |= nc.mUnwantedNetworkCapabilities;
@@ -1132,7 +1133,11 @@ public final class NetworkCapabilities implements Parcelable {
     }
 
     /**
-     * Combine a set of Capabilities to this one.  Useful for coming up with the complete set
+     * Combine a set of Capabilities to this one.  Useful for coming up with the complete set.
+     * <p>
+     * Note that this method may break an invariant of having a particular capability in either
+     * wanted or unwanted lists but never in both.  Requests that have the same capability in
+     * both lists will never be satisfied.
      * @hide
      */
     public void combineCapabilities(NetworkCapabilities nc) {
diff --git a/tests/net/java/android/net/NetworkCapabilitiesTest.java b/tests/net/java/android/net/NetworkCapabilitiesTest.java
index 941c94de9f..8cb9aa8a7b 100644
--- a/tests/net/java/android/net/NetworkCapabilitiesTest.java
+++ b/tests/net/java/android/net/NetworkCapabilitiesTest.java
@@ -282,7 +282,7 @@ public class NetworkCapabilitiesTest {
         assertTrue("Request: " + request + ", Network:" + network,
                 request.satisfiedByNetworkCapabilities(network));
 
-        // Adding capabilities that doesn't exist in the network anyway
+        // Requesting absence of capabilities that network doesn't have. Request should satisfy.
         request.addUnwantedCapability(NET_CAPABILITY_WIFI_P2P);
         request.addUnwantedCapability(NET_CAPABILITY_NOT_METERED);
         assertTrue(request.satisfiedByNetworkCapabilities(network));
@@ -297,7 +297,6 @@ public class NetworkCapabilitiesTest {
         assertTrue(request.hasUnwantedCapability(NET_CAPABILITY_NOT_RESTRICTED));
         assertFalse(request.hasCapability(NET_CAPABILITY_NOT_RESTRICTED));
 
-
         // Now this request won't be satisfied because network contains NOT_RESTRICTED.
         assertFalse(request.satisfiedByNetworkCapabilities(network));
         network.removeCapability(NET_CAPABILITY_NOT_RESTRICTED);