Fixup various doc issues (#2015)

Sources/GRPCCore/Call/Server/RPCRouter.swift

@@ -24,8 +24,8 @@
 /// given method by calling ``removeHandler(forMethod:)``.
 ///
 /// In most cases you won't need to interact with the router directly. Instead you should register
-/// your services with ``GRPCServer/Services-swift.struct/register(_:)`` which will in turn register
-/// each method with the router.
+/// your services with ``GRPCServer/init(transport:services:interceptors:)`` which will in turn
+/// register each method with the router.
 ///
 /// You may wish to not serve all methods from your service in which case you can either:
 ///

Sources/GRPCCore/Call/Server/ServerRequest.swift

@@ -33,7 +33,7 @@ extension ServerRequest {
     ///
     /// - Parameters:
     ///   - metadata: Metadata received from the client.
-    ///   - messages: The message received from the client.
+    ///   - message: The message received from the client.
     public init(metadata: Metadata, message: Message) {
       self.metadata = metadata
       self.message = message

Sources/GRPCCore/Configuration/ServiceConfig.swift

@@ -34,11 +34,12 @@ public struct ServiceConfig: Hashable, Sendable {
   /// and hedged RPCs when the client's ratio of failures to successes exceeds a threshold.
   ///
   /// For each server name, the gRPC client will maintain a `token_count` which is initially set
-  /// to ``maxTokens``. Every outgoing RPC (regardless of service or method invoked) will change
-  /// `token_count` as follows:
+  /// to ``RetryThrottling-swift.struct/maxTokens``. Every outgoing RPC (regardless of service or
+  /// method invoked) will change `token_count` as follows:
   ///
   ///   - Every failed RPC will decrement the `token_count` by 1.
-  ///   - Every successful RPC will increment the `token_count` by ``tokenRatio``.
+  ///   - Every successful RPC will increment the `token_count` by
+  ///   ``RetryThrottling-swift.struct/tokenRatio``.
   ///
   /// If `token_count` is less than or equal to `max_tokens / 2`, then RPCs will not be retried
   /// and hedged RPCs will not be sent.

Sources/GRPCCore/GRPCClient.swift

@@ -21,10 +21,10 @@ internal import Atomics
 /// A ``GRPCClient`` communicates to a server via a ``ClientTransport``.
 ///
 /// You can start RPCs to the server by calling the corresponding method:
-/// - ``unary(request:descriptor:serializer:deserializer:handler:)``
-/// - ``clientStreaming(request:descriptor:serializer:deserializer:handler:)``
-/// - ``serverStreaming(request:descriptor:serializer:deserializer:handler:)``
-/// - ``bidirectionalStreaming(request:descriptor:serializer:deserializer:handler:)``
+/// - ``unary(request:descriptor:serializer:deserializer:options:handler:)``
+/// - ``clientStreaming(request:descriptor:serializer:deserializer:options:handler:)``
+/// - ``serverStreaming(request:descriptor:serializer:deserializer:options:handler:)``
+/// - ``bidirectionalStreaming(request:descriptor:serializer:deserializer:options:handler:)``
 ///
 /// However, in most cases you should prefer wrapping the ``GRPCClient`` with a generated stub.
 ///
@@ -163,7 +163,7 @@ public struct GRPCClient: Sendable {
   /// If you need to abruptly stop all work you should cancel the task executing this method.
   ///
   /// The client, and by extension this function, can only be run once. If the client is already
-  /// running or has already been closed then a ``ClientError`` is thrown.
+  /// running or has already been closed then a ``RuntimeError`` is thrown.
   public func run() async throws {
     let (wasNotStarted, original) = self.state.compareExchange(
       expected: .notStarted,

Sources/GRPCCore/Transport/ClientTransport.swift

@@ -40,8 +40,9 @@ public protocol ClientTransport: Sendable {
 
   /// Signal to the transport that no new streams may be created.
   ///
-  /// Existing streams may run to completion naturally but calling ``withStream(descriptor:_:)``
-  /// should result in an ``RPCError`` with code ``RPCError/Code/failedPrecondition`` being thrown.
+  /// Existing streams may run to completion naturally but calling
+  /// ``ClientTransport/withStream(descriptor:options:_:)`` should result in an ``RPCError`` with
+  /// code ``RPCError/Code/failedPrecondition`` being thrown.
   ///
   /// If you want to forcefully cancel all active streams then cancel the task
   /// running ``connect()``.

Sources/GRPCCore/Transport/ServerTransport.swift

@@ -29,7 +29,7 @@ public protocol ServerTransport: Sendable {
   /// You can call ``stopListening()`` to stop the transport from accepting new streams. Existing
   /// streams must be allowed to complete naturally. However, transports may also enforce a grace
   /// period after which any open streams may be cancelled. You can also cancel the task running
-  /// ``listen()`` to abruptly close connections and streams.
+  /// ``listen(_:)`` to abruptly close connections and streams.
   func listen(
     _ streamHandler: @escaping @Sendable (RPCStream<Inbound, Outbound>) async -> Void
   ) async throws

Sources/GRPCHTTP2Core/Client/HTTP2ClientTransport.swift

@@ -28,12 +28,12 @@ extension HTTP2ClientTransport.Config {
   public struct Compression: Sendable {
     /// The default algorithm used for compressing outbound messages.
     ///
-    /// This can be overridden on a per-call basis via ``CallOptions``.
+    /// This can be overridden on a per-call basis via `CallOptions`.
     public var algorithm: CompressionAlgorithm
 
     /// Compression algorithms enabled for inbound messages.
     ///
-    /// - Note: ``CompressionAlgorithm/none`` is always supported, even if it isn't set here.
+    /// - Note: `CompressionAlgorithm.none` is always supported, even if it isn't set here.
     public var enabledAlgorithms: CompressionAlgorithmSet
 
     /// Creates a new compression configuration.

Sources/GRPCHTTP2Core/Client/Resolver/NameResolver.swift

@@ -21,11 +21,11 @@ public import GRPCCore
 public struct NameResolver: Sendable {
   /// A sequence of name resolution results.
   ///
-  /// Resolvers may be push or pull based. Resolvers with the ``UpdateMode-swift.enum/push``
+  /// Resolvers may be push or pull based. Resolvers with the ``UpdateMode-swift.struct/push``
   /// update mode have addresses pushed to them by an external source and you should subscribe
   /// to changes in addresses by awaiting for new values in a loop.
   ///
-  /// Resolvers with the ``UpdateMode-swift.enum/pull`` update mode shouldn't be subscribed to,
+  /// Resolvers with the ``UpdateMode-swift.struct/pull`` update mode shouldn't be subscribed to,
   /// instead you should create an iterator and ask for new results as and when necessary.
   public var names: RPCAsyncSequence<NameResolutionResult, any Error>
 

Sources/GRPCHTTP2Core/Server/HTTP2ServerTransport.swift

@@ -29,7 +29,7 @@ extension HTTP2ServerTransport.Config {
   public struct Compression: Sendable {
     /// Compression algorithms enabled for inbound messages.
     ///
-    /// - Note: ``CompressionAlgorithm/none`` is always supported, even if it isn't set here.
+    /// - Note: `CompressionAlgorithm.none` is always supported, even if it isn't set here.
     public var enabledAlgorithms: CompressionAlgorithmSet
 
     /// Creates a new compression configuration.

Sources/GRPCHTTP2TransportNIOPosix/HTTP2ServerTransport+Posix.swift

@@ -294,7 +294,7 @@ extension HTTP2ServerTransport {
 
 @available(macOS 15.0, iOS 18.0, watchOS 11.0, tvOS 18.0, visionOS 2.0, *)
 extension HTTP2ServerTransport.Posix {
-  /// Configuration for the ``GRPCHTTP2TransportNIOPosix/GRPCHTTP2Core/HTTP2ServerTransport/Posix``.
+  /// Config for the `Posix` transport.
   public struct Config: Sendable {
     /// Compression configuration.
     public var compression: HTTP2ServerTransport.Config.Compression

Sources/GRPCHTTP2TransportNIOTransportServices/HTTP2ServerTransport+TransportServices.swift

@@ -286,7 +286,7 @@ extension HTTP2ServerTransport {
 
 @available(macOS 15.0, iOS 18.0, watchOS 11.0, tvOS 18.0, visionOS 2.0, *)
 extension HTTP2ServerTransport.TransportServices {
-  /// Configuration for the ``GRPCHTTP2TransportNIOTransportServices/GRPCHTTP2Core/HTTP2ServerTransport/TransportServices``.
+  /// Configuration for the `TransportServices` transport.
   public struct Config: Sendable {
     /// Compression configuration.
     public var compression: HTTP2ServerTransport.Config.Compression

Sources/GRPCInProcessTransport/InProcessClientTransport.swift

@@ -22,15 +22,13 @@ public import GRPCCore
 /// involved, as the client and server will communicate directly with each other via in-process streams.
 ///
 /// To use this client, you'll have to provide an ``InProcessServerTransport`` upon creation, as well
-/// as a ``ClientRPCExecutionConfigurationCollection``, containing a set of
-/// ``ClientRPCExecutionConfiguration``s which are specific, per-method configurations for your
-/// transport.
+/// as a ``ServiceConfig``.
 ///
 /// Once you have a client, you must keep a long-running task executing ``connect()``, which
 /// will return only once all streams have been finished and ``close()`` has been called on this client; or
 /// when the containing task is cancelled.
 ///
-/// To execute requests using this client, use ``withStream(descriptor:_:)``. If this function is
+/// To execute requests using this client, use ``withStream(descriptor:options:_:)``. If this function is
 /// called before ``connect()`` is called, then any streams will remain pending and the call will
 /// block until ``connect()`` is called or the task is cancelled.
 ///
@@ -187,7 +185,7 @@ public struct InProcessClientTransport: ClientTransport {
 
   /// Signal to the transport that no new streams may be created.
   ///
-  /// Existing streams may run to completion naturally but calling ``withStream(descriptor:_:)``
+  /// Existing streams may run to completion naturally but calling ``withStream(descriptor:options:_:)``
   /// will result in an ``RPCError`` with code ``RPCError/Code/failedPrecondition`` being thrown.
   ///
   /// If you want to forcefully cancel all active streams then cancel the task running ``connect()``.

Sources/GRPCInProcessTransport/InProcessServerTransport.swift

@@ -21,7 +21,7 @@ public import GRPCCore
 /// This is useful when you're interested in testing your application without any actual networking layers
 /// involved, as the client and server will communicate directly with each other via in-process streams.
 ///
-/// To use this server, you call ``listen()`` and iterate over the returned `AsyncSequence` to get all
+/// To use this server, you call ``listen(_:)`` and iterate over the returned `AsyncSequence` to get all
 /// RPC requests made from clients (as ``RPCStream``s).
 /// To stop listening to new requests, call ``stopListening()``.
 ///
@@ -69,9 +69,6 @@ public struct InProcessServerTransport: ServerTransport, Sendable {
 
   /// Stop listening to any new ``RPCStream`` publications.
   ///
-  /// All further calls to ``acceptStream(_:)`` will not produce any new elements on the
-  /// ``RPCAsyncSequence`` returned by ``listen()``.
-  ///
   /// - SeeAlso: ``ServerTransport``
   public func stopListening() {
     self.newStreamsContinuation.finish()

Sources/GRPCProtobuf/Coding.swift

@@ -21,7 +21,7 @@ public import SwiftProtobuf
 public struct ProtobufSerializer<Message: SwiftProtobuf.Message>: GRPCCore.MessageSerializer {
   public init() {}
 
-  /// Serializes a ``Message`` into a sequence of bytes.
+  /// Serializes a `Message` into a sequence of bytes.
   ///
   /// - Parameter message: The message to serialize.
   /// - Returns: An array of serialized bytes representing the message.
@@ -42,7 +42,7 @@ public struct ProtobufSerializer<Message: SwiftProtobuf.Message>: GRPCCore.Messa
 public struct ProtobufDeserializer<Message: SwiftProtobuf.Message>: GRPCCore.MessageDeserializer {
   public init() {}
 
-  /// Deserializes a sequence of bytes into a ``Message``.
+  /// Deserializes a sequence of bytes into a `Message`.
   ///
   /// - Parameter serializedMessageBytes: The array of bytes to deserialize.
   /// - Returns: The deserialized message.