Improve some code comments (#8361)

okhttp-testing-support/src/test/kotlin/okhttp3/testing/PlatformRuleTest.kt

@@ -20,7 +20,7 @@ import org.junit.jupiter.api.Test
 import org.junit.jupiter.api.extension.RegisterExtension
 
 /**
- * Sanity test for checking which environment and IDE is picking up.
+ * Validates which environment is used by the IDE.
  */
 class PlatformRuleTest {
   @RegisterExtension @JvmField

okhttp/src/main/kotlin/okhttp3/internal/connection/RouteDatabase.kt

@@ -18,7 +18,7 @@ package okhttp3.internal.connection
 import okhttp3.Route
 
 /**
- * A blacklist of failed routes to avoid when creating a new connection to a target address. This is
+ * A denylist of failed routes to avoid when creating a new connection to a target address. This is
  * used so that OkHttp can learn from its mistakes: if there was a failure attempting to connect to
  * a specific IP address or proxy server, that failure is remembered and alternate routes are
  * preferred.

okhttp/src/main/kotlin/okhttp3/internal/tls/OkHostnameVerifier.kt

@@ -112,19 +112,18 @@ object OkHostnameVerifier : HostnameVerifier {
   ): Boolean {
     var hostname = hostname
     var pattern = pattern
-    // Basic sanity checks
     if (hostname.isNullOrEmpty() ||
       hostname.startsWith(".") ||
       hostname.endsWith("..")
     ) {
-      // Invalid domain name
+      // Invalid domain name.
       return false
     }
     if (pattern.isNullOrEmpty() ||
       pattern.startsWith(".") ||
       pattern.endsWith("..")
     ) {
-      // Invalid pattern/domain name
+      // Invalid pattern.
       return false
     }
 

okhttp/src/test/java/okhttp3/internal/cache/DiskLruCacheTest.kt

@@ -840,7 +840,7 @@ class DiskLruCacheTest {
     }
     taskFaker.runNextTask()
 
-    // Sanity check that a rebuilt journal behaves normally.
+    // Check that a rebuilt journal behaves normally.
     assertValue("a", "a", "a")
     assertValue("b", "b", "b")
   }

samples/guide/src/main/java/okhttp3/recipes/CheckHandshake.java

@@ -28,14 +28,14 @@
 public final class CheckHandshake {
   /** Rejects otherwise-trusted certificates. */
   private static final Interceptor CHECK_HANDSHAKE_INTERCEPTOR = new Interceptor() {
-    final Set<String> blacklist = Collections.singleton(
+    final Set<String> denylist = Collections.singleton(
         "sha256/afwiKY3RxoMmLkuRW1l7QsPZTJPwDS2pdDROQjXw8ig=");
 
     @Override public Response intercept(Chain chain) throws IOException {
       for (Certificate certificate : chain.connection().handshake().peerCertificates()) {
         String pin = CertificatePinner.pin(certificate);
-        if (blacklist.contains(pin)) {
-          throw new IOException("Blacklisted peer certificate: " + pin);
+        if (denylist.contains(pin)) {
+          throw new IOException("Denylisted peer certificate: " + pin);
         }
       }
       return chain.proceed(chain.request());