Add index docc page and fix comment links (#1473)

# Motivation
We want to be able to generate proper docc pages.

# Modification
This PR adds a new index page for the `GRPC` module which is adapting the current `README`. Furthermore, it fixes a bunch of links in the doc comments so that they resolve properly.

# Result
We can now build better docc pages.

Author: FranzBusch

README.md

@@ -54,7 +54,7 @@ package dependency to your `Package.swift`:
 
 ```swift
 dependencies: [
-  .package(url: "https://github.com/grpc/grpc-swift.git", from: "1.0.0")
+  .package(url: "https://github.com/grpc/grpc-swift.git", from: "1.9.0")
 ]
 ```
 

Sources/GRPC/AsyncAwaitSupport/GRPCAsyncBidirectionalStreamingCall.swift

@@ -17,7 +17,7 @@
 
 import NIOHPACK
 
-/// Async-await variant of BidirectionalStreamingCall.
+/// Async-await variant of ``BidirectionalStreamingCall``.
 @available(macOS 10.15, iOS 13, tvOS 13, watchOS 6, *)
 public struct GRPCAsyncBidirectionalStreamingCall<Request: Sendable, Response: Sendable>: Sendable {
   private let call: Call<Request, Response>

Sources/GRPC/AsyncAwaitSupport/GRPCAsyncClientStreamingCall.swift

@@ -17,7 +17,7 @@
 
 import NIOHPACK
 
-/// Async-await variant of `ClientStreamingCall`.
+/// Async-await variant of ``ClientStreamingCall``.
 @available(macOS 10.15, iOS 13, tvOS 13, watchOS 6, *)
 public struct GRPCAsyncClientStreamingCall<Request: Sendable, Response: Sendable>: Sendable {
   private let call: Call<Request, Response>

Sources/GRPC/AsyncAwaitSupport/GRPCAsyncRequestStreamWriter.swift

@@ -46,7 +46,7 @@ public struct GRPCAsyncRequestStreamWriter<Request: Sendable>: Sendable {
   /// before sending another request. Callers who do not need this guarantee do not have to `await`
   /// the completion of this call and may send messages concurrently from multiple ``Task``s.
   /// However, it is important to note that no more than 16 writes may be pending at any one time
-  /// and attempting to exceed this will result in an ``GRPCAsyncWriterError.tooManyPendingWrites``
+  /// and attempting to exceed this will result in an ``GRPCAsyncWriterError/tooManyPendingWrites``
   /// error being thrown.
   ///
   /// Callers must call ``finish()`` when they have no more requests left to send.

Sources/GRPC/AsyncAwaitSupport/GRPCAsyncServerCallContext.swift

@@ -32,10 +32,10 @@ public struct GRPCAsyncServerCallContext: Sendable {
     Response(contextProvider: self.contextProvider)
   }
 
-  /// Access the `UserInfo` dictionary which is shared with the interceptor contexts for this RPC.
+  /// Access the ``UserInfo`` dictionary which is shared with the interceptor contexts for this RPC.
   ///
-  /// - Important: While `UserInfo` has value-semantics, this function accesses a reference
-  ///   wrapped `UserInfo`. The contexts passed to interceptors provide the same reference. As such
+  /// - Important: While ``UserInfo`` has value-semantics, this function accesses a reference
+  ///   wrapped ``UserInfo``. The contexts passed to interceptors provide the same reference. As such
   ///   this may be used as a mechanism to pass information between interceptors and service
   ///   providers.
   public func withUserInfo<Result: Sendable>(
@@ -44,10 +44,10 @@ public struct GRPCAsyncServerCallContext: Sendable {
     return try await self.contextProvider.withUserInfo(body)
   }
 
-  /// Modify the `UserInfo` dictionary which is shared with the interceptor contexts for this RPC.
+  /// Modify the ``UserInfo`` dictionary which is shared with the interceptor contexts for this RPC.
   ///
-  /// - Important: While `UserInfo` has value-semantics, this function accesses a reference
-  ///   wrapped `UserInfo`. The contexts passed to interceptors provide the same reference. As such
+  /// - Important: While ``UserInfo`` has value-semantics, this function accesses a reference
+  ///   wrapped ``UserInfo``. The contexts passed to interceptors provide the same reference. As such
   ///   this may be used as a mechanism to pass information between interceptors and service
   ///   providers.
   public func withMutableUserInfo<Result: Sendable>(

Sources/GRPC/AsyncAwaitSupport/GRPCAsyncServerStreamingCall.swift

@@ -17,7 +17,7 @@
 
 import NIOHPACK
 
-/// Async-await variant of `ServerStreamingCall`.
+/// Async-await variant of ``ServerStreamingCall``.
 @available(macOS 10.15, iOS 13, tvOS 13, watchOS 6, *)
 public struct GRPCAsyncServerStreamingCall<Request: Sendable, Response: Sendable> {
   private let call: Call<Request, Response>

Sources/GRPC/AsyncAwaitSupport/GRPCAsyncUnaryCall.swift

@@ -19,7 +19,7 @@ import NIOHPACK
 
 /// A unary gRPC call. The request is sent on initialization.
 ///
-/// Note: while this object is a `struct`, its implementation delegates to `Call`. It therefore
+/// Note: while this object is a `struct`, its implementation delegates to ``Call``. It therefore
 /// has reference semantics.
 @available(macOS 10.15, iOS 13, tvOS 13, watchOS 6, *)
 public struct GRPCAsyncUnaryCall<Request: Sendable, Response: Sendable>: Sendable {

Sources/GRPC/CallHandlers/ClientStreamingServerHandler.swift

@@ -43,7 +43,7 @@ public final class ClientStreamingServerHandler<
   @usableFromInline
   internal let context: CallHandlerContext
 
-  /// A reference to a `UserInfo`.
+  /// A reference to a ``UserInfo``.
   @usableFromInline
   internal let userInfoRef: Ref<UserInfo>
 

Sources/GRPC/CallHandlers/ServerHandlerProtocol.swift

@@ -20,7 +20,7 @@ import NIOHPACK
 /// On receiving a new RPC, gRPC will ask all available service providers for an instance of this
 /// protocol in order to handle the RPC.
 ///
-/// See also: `CallHandlerProvider.handle(method:context:)`
+/// See also: ``CallHandlerProvider/handle(method:context:)``.
 public protocol GRPCServerHandlerProtocol {
   /// Called when request headers have been received at the start of an RPC.
   /// - Parameter metadata: The request headers.

Sources/GRPC/CallOptions.swift

@@ -41,9 +41,11 @@ public struct CallOptions: GRPCSendable {
   /// for the remote peer to use for encoding responses.
   ///
   /// Compression may also be disabled at the message-level for streaming requests (i.e. client
-  /// streaming and bidirectional streaming RPCs) by setting `compression` to `.disabled` in
-  /// `sendMessage(_:compression)`, `sendMessage(_:compression:promise)`,
-  /// `sendMessages(_:compression)` or `sendMessages(_:compression:promise)`.
+  /// streaming and bidirectional streaming RPCs) by setting `compression` to ``Compression/disabled`` in
+  /// ``StreamingRequestClientCall/sendMessage(_:compression:)-uvtc``,
+  /// ``StreamingRequestClientCall/sendMessage(_:compression:promise:)`` ,
+  /// ``StreamingRequestClientCall/sendMessages(_:compression:)-55vb3`` or
+  /// ``StreamingRequestClientCall/sendMessage(_:compression:promise:)`.
   ///
   /// Note that enabling `compression` via the `sendMessage` or `sendMessages` methods only applies
   /// if encoding has been specified in these options.
@@ -52,20 +54,20 @@ public struct CallOptions: GRPCSendable {
   /// Whether the call is cacheable.
   public var cacheable: Bool
 
-  /// How IDs should be provided for requests. Defaults to `.autogenerated`.
+  /// How IDs should be provided for requests. Defaults to ``RequestIDProvider-swift.struct/autogenerated``.
   ///
   /// The request ID is used for logging and will be added to the headers of a call if
   /// `requestIDHeader` is specified.
   ///
-  /// - Important: When setting `CallOptions` at the client level, `.userDefined` should __not__ be
+  /// - Important: When setting ``CallOptions`` at the client level, ``RequestIDProvider-swift.struct/userDefined(_:)`` should __not__ be
   /// used otherwise each request will have the same ID.
   public var requestIDProvider: RequestIDProvider
 
   /// The name of the header to use when adding a request ID to a call, e.g. "x-request-id". If the
   /// value is `nil` (the default) then no additional header will be added.
   ///
   /// Setting this value will add a request ID to the headers of the call these options are used
-  /// with. The request ID will be provided by `requestIDProvider` and will also be used in log
+  /// with. The request ID will be provided by ``requestIDProvider-swift.property`` and will also be used in log
   /// messages associated with the call.
   public var requestIDHeader: String?
 
@@ -81,7 +83,7 @@ public struct CallOptions: GRPCSendable {
 
   /// A logger used for the call. Defaults to a no-op logger.
   ///
-  /// If a `requestIDProvider` exists then a request ID will automatically attached to the logger's
+  /// If a ``requestIDProvider-swift.property`` exists then a request ID will automatically attached to the logger's
   /// metadata using the 'grpc-request-id' key.
   public var logger: Logger
 
@@ -166,7 +168,7 @@ extension CallOptions {
 
     /// Specify an ID to be used.
     ///
-    /// - Important: this should only be used when `CallOptions` are passed directly to the call.
+    /// - Important: this should only be used when ``CallOptions`` are passed directly to the call.
     ///   If it is used for the default options on a client then all calls with have the same ID.
     public static func userDefined(_ requestID: String) -> RequestIDProvider {
       return RequestIDProvider(.static(requestID))