testing: Make more obvious that GrpcServerRule has been replaced

ejona86 · ejona86 · commit 9b55aed12ef5 · 2021-07-12T14:46:12.000-05:00
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.
diff --git a/testing/src/main/java/io/grpc/testing/GrpcCleanupRule.java b/testing/src/main/java/io/grpc/testing/GrpcCleanupRule.java
@@ -41,6 +41,34 @@
  * 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")
diff --git a/testing/src/main/java/io/grpc/testing/GrpcServerRule.java b/testing/src/main/java/io/grpc/testing/GrpcServerRule.java
@@ -34,14 +34,16 @@
 
 /**
  * {@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
- * 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
+ * a {@link MutableHandlerRegistry} for adding services. Prefer {@link GrpcCleanupRule} in new code.
+ *
+ * <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}
- * {@link GrpcCleanupRule} than {@code GrpcServerRule} in unit tests.
+ * GrpcServerRule}. Little benefit comes from proactively migrating existing code from {@code
+ * 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()}.
