testing: Make more obvious that GrpcServerRule has been replaced

The previous text did explain to use GrpcCleanupRule, but a user just
skimming might not read the long paragraph. Now we have a TL;DR.

testing/src/main/java/io/grpc/testing/GrpcCleanupRule.java

@@ -41,6 +41,34 @@ import org.junit.runners.model.Statement;
  * the end of the test. If any of the resources registered to the rule can not be successfully
  * released, the test will fail.
  *
+ * <p>Example usage:
+ * <pre>{@code @Rule public final GrpcCleanupRule grpcCleanup = new GrpcCleanupRule();
+ * ...
+ * // The Channel and Server can be created in any order
+ * grpcCleanup.register(
+ *     InProcessServerBuilder.forName("my-test-case")
+ *         .directExecutor()
+ *         .addService(serviceImpl)
+ *         .build()
+ *         .start());
+ * ManagedChannel channel = grpcCleanup.register(
+ *     InProcessChannelBuilder.forName("my-test-case")
+ *         .directExecutor()
+ *         .build());
+ * }</pre>
+ *
+ * <p>To use as a replacement for {@link GrpcServerRule}:
+ * <pre>{@code String serverName = InProcessServerBuilder.generateName();
+ * MutableHandlerRegistry serviceRegistry = new MutableHandlerRegistry();
+ * Server server = grpcCleanup.register(
+ *     InProcessServerBuilder.forName(serverName)
+ *         .fallbackHandlerRegistry(serviceRegistry)
+ *         .build()
+ *         .start());
+ * ManagedChannel channel = grpcCleanup.register(
+ *     InProcessChannelBuilder.forName(serverName).build());
+ * }</pre>
+ *
  * @since 1.13.0
  */
 @ExperimentalApi("https://github.com/grpc/grpc-java/issues/2488")

testing/src/main/java/io/grpc/testing/GrpcServerRule.java

@@ -34,14 +34,16 @@ import org.junit.rules.TestRule;
 
 /**
  * {@code GrpcServerRule} is a JUnit {@link TestRule} that starts an in-process gRPC service with
- * a {@link MutableHandlerRegistry} for adding services. It is particularly useful for mocking out
+ * a {@link MutableHandlerRegistry} for adding services. Prefer {@link GrpcCleanupRule} in new code.
- * external gRPC-based services and asserting that the expected requests were made. However, due to
+ *
- * it's limitation that {@code GrpcServerRule} does not support useful features such as transport
+ * <p>{@code GrpcServerRule} is useful for testing gRPC-based clients and services. However,
+ * because {@code GrpcServerRule} does not support useful features such as transport
  * types other than in-process, multiple channels per server, custom channel or server builder
  * options, and configuration inside individual test methods, users would end up to a difficult
  * situation when later they want to make extensions to their tests that were using {@code
- * GrpcServerRule}. So in general it is more favorable to use the more flexible {@code TestRule}
+ * GrpcServerRule}. Little benefit comes from proactively migrating existing code from {@code
- * {@link GrpcCleanupRule} than {@code GrpcServerRule} in unit tests.
+ * GrpcServerRule}, but new code is better served by explicit channel and server creation with
+ * {@code GrpcCleanupRule} managing resource lifetimes.
  *
  * <p>An {@link AbstractStub} can be created against this service by using the
  * {@link ManagedChannel} provided by {@link GrpcServerRule#getChannel()}.