Group DocC docs in the index page (#2160)

Motivation:

Grouping DocC docs by their area makes it easier to find things.

Modifications:

- Group docs in the index page
- Update various docs

Result:

Better docs

Sources/GRPCCore/Configuration/MethodConfig.swift

@@ -18,6 +18,7 @@
 ///
 /// See also: https://github.com/grpc/grpc-proto/blob/0b30c8c05277ab78ec72e77c9cbf66a26684673d/grpc/service_config/service_config.proto
 public struct MethodConfig: Hashable, Sendable {
+  /// The name of a method to which the method config applies.
   public struct Name: Sendable, Hashable {
     /// The name of the service, including the namespace.
     ///
@@ -143,6 +144,7 @@ public struct MethodConfig: Hashable, Sendable {
   }
 }
 
+/// Whether an RPC should be retried or hedged.
 public struct RPCExecutionPolicy: Hashable, Sendable {
   @usableFromInline
   enum Wrapped: Hashable, Sendable {

Sources/GRPCCore/Configuration/ServiceConfig.swift

@@ -16,7 +16,12 @@
 
 /// Service configuration values.
 ///
-/// See also: https://github.com/grpc/grpc-proto/blob/0b30c8c05277ab78ec72e77c9cbf66a26684673d/grpc/service_config/service_config.proto
+/// A service config mostly contains parameters describing how clients connecting to a service
+/// should behave (for example, the load balancing policy to use).
+///
+/// The schema is described by [`grpc/service_config/service_config.proto`](https://github.com/grpc/grpc-proto/blob/0b30c8c05277ab78ec72e77c9cbf66a26684673d/grpc/service_config/service_config.proto)
+/// in the `grpc/grpc-proto` GitHub repository although gRPC uses it in its JSON form rather than
+/// the Protobuf form.
 public struct ServiceConfig: Hashable, Sendable {
   /// Per-method configuration.
   public var methodConfig: [MethodConfig]

Sources/GRPCCore/Documentation.docc/Documentation.md

@@ -52,7 +52,7 @@ as tutorials.
 ### Essentials
 
 - <doc:Generating-stubs>
-- <doc:Errors>
+- <doc:Error-handling>
 
 ### Project Information
 
@@ -64,3 +64,83 @@ Resources for developers working on gRPC Swift:
 
 - <doc:Design>
 - <doc:Benchmarks>
+
+### Client and Server
+
+- ``GRPCClient``
+- ``GRPCServer``
+- ``withGRPCClient(transport:interceptors:isolation:handleClient:)``
+- ``withGRPCClient(transport:interceptorPipeline:isolation:handleClient:)``
+- ``withGRPCServer(transport:services:interceptors:isolation:handleServer:)``
+- ``withGRPCServer(transport:services:interceptorPipeline:isolation:handleServer:)``
+
+### Request and response types
+
+- ``ClientRequest``
+- ``StreamingClientRequest``
+- ``ClientResponse``
+- ``StreamingClientResponse``
+- ``ServerRequest``
+- ``StreamingServerRequest``
+- ``ServerResponse``
+- ``StreamingServerResponse``
+
+### Service definition and routing
+
+- ``RegistrableRPCService``
+- ``RPCRouter``
+
+### Interceptors
+
+- ``ClientInterceptor``
+- ``ServerInterceptor``
+- ``ClientContext``
+- ``ServerContext``
+- ``ClientInterceptorPipelineOperation``
+- ``ServerInterceptorPipelineOperation``
+
+### RPC descriptors
+
+- ``MethodDescriptor``
+- ``ServiceDescriptor``
+
+### Service config
+
+- ``ServiceConfig``
+- ``MethodConfig``
+- ``HedgingPolicy``
+- ``RetryPolicy``
+- ``RPCExecutionPolicy``
+
+### Serialization
+
+- ``MessageSerializer``
+- ``MessageDeserializer``
+- ``CompressionAlgorithm``
+- ``CompressionAlgorithmSet``
+
+### Transport protocols and supporting types
+
+- ``ClientTransport``
+- ``ServerTransport``
+- ``RPCRequestPart``
+- ``RPCResponsePart``
+- ``Status``
+- ``Metadata``
+- ``RetryThrottle``
+- ``RPCStream``
+- ``RPCWriterProtocol``
+- ``ClosableRPCWriterProtocol``
+- ``RPCWriter``
+- ``RPCAsyncSequence``
+
+### Cancellation
+
+- ``withServerContextRPCCancellationHandle(_:)``
+- ``withRPCCancellationHandler(operation:onCancelRPC:)``
+
+### Errors
+
+- ``RPCError``
+- ``RPCErrorConvertible``
+- ``RuntimeError``

Sources/GRPCCore/Streaming/RPCWriterProtocol.swift

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 
-/// A sink for values which are produced over time.
+/// A type into which values can be written indefinitely.
 public protocol RPCWriterProtocol<Element>: Sendable {
   /// The type of value written.
   associatedtype Element: Sendable
@@ -49,6 +49,7 @@ extension RPCWriterProtocol {
   }
 }
 
+/// A type into which values can be written until it is finished.
 public protocol ClosableRPCWriterProtocol<Element>: RPCWriterProtocol {
   /// Indicate to the writer that no more writes are to be accepted.
   ///

Sources/GRPCCore/Transport/ClientTransport.swift

@@ -14,6 +14,17 @@
  * limitations under the License.
  */
 
+/// A type that provides a long-lived bidirectional communication channel to a server.
+///
+/// The client transport is responsible for providing streams to a backend on top of which an
+/// RPC can be executed. A typical transport implementation will establish and maintain connections
+/// to a server (or servers) and manage these over time, potentially closing idle connections and
+/// creating new ones on demand. As such transports can be expensive to create and as such are
+/// intended to be used as long-lived objects which exist for the lifetime of your application.
+///
+/// gRPC provides an in-process transport in the `GRPCInProcessTransport` module and HTTP/2
+/// transport built on top of SwiftNIO in the https://github.com/grpc/grpc-swift-nio-transport
+/// package.
 public protocol ClientTransport: Sendable {
   typealias Inbound = RPCAsyncSequence<RPCResponsePart, any Error>
   typealias Outbound = RPCWriter<RPCRequestPart>.Closable

Sources/GRPCCore/Transport/ServerTransport.swift

@@ -14,7 +14,14 @@
  * limitations under the License.
  */
 
-/// A protocol server transport implementations must conform to.
+/// A type that provides a bidirectional communication channel with a client.
+///
+/// The server transport is responsible for handling connections created by a client and
+/// the multiplexing of those connections into streams corresponding to RPCs.
+///
+/// gRPC provides an in-process transport in the `GRPCInProcessTransport` module and HTTP/2
+/// transport built on top of SwiftNIO in the https://github.com/grpc/grpc-swift-nio-transport
+/// package.
 public protocol ServerTransport: Sendable {
   typealias Inbound = RPCAsyncSequence<RPCRequestPart, any Error>
   typealias Outbound = RPCWriter<RPCResponsePart>.Closable