From 010756b6bfeac28b7b71fdec89dee5016a7349ac Mon Sep 17 00:00:00 2001 From: George Barnett Date: Wed, 15 Jan 2025 08:54:15 +0000 Subject: [PATCH] Group DocC docs in the index page 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 --- .../GRPCCore/Configuration/MethodConfig.swift | 2 + .../Configuration/ServiceConfig.swift | 7 +- .../Articles/{Errors.md => Error-handling.md} | 0 .../Documentation.docc/Documentation.md | 82 ++++++++++++++++++- .../Streaming/RPCWriterProtocol.swift | 3 +- .../GRPCCore/Transport/ClientTransport.swift | 11 +++ .../GRPCCore/Transport/ServerTransport.swift | 9 +- 7 files changed, 110 insertions(+), 4 deletions(-) rename Sources/GRPCCore/Documentation.docc/Articles/{Errors.md => Error-handling.md} (100%) diff --git a/Sources/GRPCCore/Configuration/MethodConfig.swift b/Sources/GRPCCore/Configuration/MethodConfig.swift index 23a867926..2de35e5a4 100644 --- a/Sources/GRPCCore/Configuration/MethodConfig.swift +++ b/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 { diff --git a/Sources/GRPCCore/Configuration/ServiceConfig.swift b/Sources/GRPCCore/Configuration/ServiceConfig.swift index 316ad8b61..805e5ea59 100644 --- a/Sources/GRPCCore/Configuration/ServiceConfig.swift +++ b/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] diff --git a/Sources/GRPCCore/Documentation.docc/Articles/Errors.md b/Sources/GRPCCore/Documentation.docc/Articles/Error-handling.md similarity index 100% rename from Sources/GRPCCore/Documentation.docc/Articles/Errors.md rename to Sources/GRPCCore/Documentation.docc/Articles/Error-handling.md diff --git a/Sources/GRPCCore/Documentation.docc/Documentation.md b/Sources/GRPCCore/Documentation.docc/Documentation.md index f70913cea..e14f03669 100644 --- a/Sources/GRPCCore/Documentation.docc/Documentation.md +++ b/Sources/GRPCCore/Documentation.docc/Documentation.md @@ -52,7 +52,7 @@ as tutorials. ### Essentials - -- +- ### Project Information @@ -64,3 +64,83 @@ Resources for developers working on gRPC Swift: - - + +### 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`` diff --git a/Sources/GRPCCore/Streaming/RPCWriterProtocol.swift b/Sources/GRPCCore/Streaming/RPCWriterProtocol.swift index 076043e30..2f1c706d5 100644 --- a/Sources/GRPCCore/Streaming/RPCWriterProtocol.swift +++ b/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: 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: RPCWriterProtocol { /// Indicate to the writer that no more writes are to be accepted. /// diff --git a/Sources/GRPCCore/Transport/ClientTransport.swift b/Sources/GRPCCore/Transport/ClientTransport.swift index a86a79fea..dd6bcb52a 100644 --- a/Sources/GRPCCore/Transport/ClientTransport.swift +++ b/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 typealias Outbound = RPCWriter.Closable diff --git a/Sources/GRPCCore/Transport/ServerTransport.swift b/Sources/GRPCCore/Transport/ServerTransport.swift index 15148c78e..a7b926019 100644 --- a/Sources/GRPCCore/Transport/ServerTransport.swift +++ b/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 typealias Outbound = RPCWriter.Closable