Apply missed review nits from #454 and #460

README.md

@@ -19,7 +19,7 @@ Connect is the **easiest way to build modern APIs**.
 
 ## Why Connect?
 
-Building an API usually means writing the same types at least twice: once on the server, and once in every client. Connect makes this simple: define your API schema using Protobuf, and Connect generates type-safe server stubs and idiomatic client libraries in **every major language**, including for your frontend. All that's left to write is your business logic, in plain Python.
+Building an API usually means writing the same types at least twice: once on the server, and once in every client. Connect makes this simple—define your API schema using Protobuf, and Connect generates type-safe server stubs and idiomatic client libraries in **every major language**, including for your frontend. All that's left to write is your business logic, in plain Python.
 
 Connect already works with your current tech stack:
 
@@ -121,9 +121,8 @@ class MyHelloService(HelloService):
 
 app = HelloServiceASGIApplication(MyHelloService())
 
-# Run with any ASGI server. gRPC and full-duplex bidirectional streaming
-# need HTTP/2, which pyvoy supports:
-# pyvoy server:app --port 8080
+# Run with any ASGI server, e.g. uvicorn:
+# uvicorn server:app --port 8080
 ```
 
 Client libraries are automatically generated for you. Here's what the async client looks like:

connectrpc-grpcreflect/README.md

@@ -32,10 +32,10 @@ app = Starlette(
 )
 ```
 
-`reflection_apps` returns applications for both `grpc.reflection.v1` and
-`grpc.reflection.v1alpha`. Mount both: each lists the other, and a client
-that calls v1alpha gets a 404 if it isn't mounted. Use
-`reflection_apps_sync` for WSGI.
+`reflection_apps` (ASGI) and `reflection_apps_sync` (WSGI) return
+applications for both `grpc.reflection.v1` and `grpc.reflection.v1alpha`. It
+is recommended to mount both: even if only one is mounted, both are returned
+in `ListServices`, and a client that calls the unmounted service gets a 404.
 
 Reflection uses the gRPC protocol which requires a server that supports HTTP/2
 trailers such as [pyvoy](https://pyvoy.dev).

connectrpc-grpcreflect/connectrpc_grpcreflect/_apps.py

@@ -26,8 +26,9 @@ def reflection_apps(
 ) -> tuple[ServerReflectionASGIApplication, ServerReflectionAlphaASGIApplication]:
     """Create ASGI applications for the v1 and v1alpha gRPC reflection services.
 
-    Both services list each other, so serve both: mount each application at its
-    `path`.
+    Mount both applications, each at its `path`: even if only one is mounted,
+    both services are returned in `ListServices`, and a client that calls the
+    unmounted service gets a 404.
 
     Args:
         *descs: The descriptors to make available for reflection, as accepted by
@@ -45,8 +46,9 @@ def reflection_apps_sync(
 ) -> tuple[ServerReflectionWSGIApplication, ServerReflectionAlphaWSGIApplication]:
     """Create WSGI applications for the v1 and v1alpha gRPC reflection services.
 
-    Both services list each other, so serve both: mount each application at its
-    `path`.
+    Mount both applications, each at its `path`: even if only one is mounted,
+    both services are returned in `ListServices`, and a client that calls the
+    unmounted service gets a 404.
 
     Args:
         *descs: The descriptors to make available for reflection, as accepted by