From e4bf649e2e89c01a9b06cc3cdc505fc18c1c7a23 Mon Sep 17 00:00:00 2001
From: George Barnett <gbarnett@apple.com>
Date: Fri, 17 Jan 2025 13:39:55 +0000
Subject: [PATCH] Group docs and fix visibility (#57)

Motivation:

Grouping docs in the DocC index is a useful way to make the docs more
approachable.

Modifications:

- Group the docs
- Add a few more docs
- Change the visibility of an accidentally public type

Result:

Better docs
---
 .spi.yml                                      |  2 +-
 .../Connection/LoadBalancers/Subchannel.swift |  2 ++
 .../Documentation.docc/Documentation.md       | 34 +++++++++++++++++++
 .../Server/Connection/ServerConnection.swift  |  4 +--
 4 files changed, 39 insertions(+), 3 deletions(-)
 create mode 100644 Sources/GRPCNIOTransportCore/Documentation.docc/Documentation.md

diff --git a/.spi.yml b/.spi.yml
index 3f5e0d1..4fdc9ed 100644
--- a/.spi.yml
+++ b/.spi.yml
@@ -1,5 +1,5 @@
 version: 1
 builder:
   configs:
-    - documentation_targets: [GRPCNIOTransportHTTP2, GRPCNIOTransportHTTP2Posix, GRPCNIOTransportHTTP2TransportServices]
+    - documentation_targets: [GRPCNIOTransportCore, GRPCNIOTransportHTTP2, GRPCNIOTransportHTTP2Posix, GRPCNIOTransportHTTP2TransportServices]
       swift_version: 6.0
diff --git a/Sources/GRPCNIOTransportCore/Client/Connection/LoadBalancers/Subchannel.swift b/Sources/GRPCNIOTransportCore/Client/Connection/LoadBalancers/Subchannel.swift
index 41387f6..727bd2f 100644
--- a/Sources/GRPCNIOTransportCore/Client/Connection/LoadBalancers/Subchannel.swift
+++ b/Sources/GRPCNIOTransportCore/Client/Connection/LoadBalancers/Subchannel.swift
@@ -380,6 +380,7 @@ extension Subchannel {
 }
 
 extension Subchannel {
+  /// ```
   ///            ┌───────────────┐
   ///   ┌───────▶│ NOT CONNECTED │───────────shutDown─────────────┐
   ///   │        └───────────────┘                                │
@@ -404,6 +405,7 @@ extension Subchannel {
   ///   │        ┌───────────────┐      │      ┌───────────────┐  │
   ///   └────────│  GOING AWAY   │──────┘      │   SHUT DOWN   │◀─┘
   ///            └───────────────┘             └───────────────┘
+  /// ```
   private enum State {
     /// Not connected and not actively connecting.
     case notConnected(NotConnected)
diff --git a/Sources/GRPCNIOTransportCore/Documentation.docc/Documentation.md b/Sources/GRPCNIOTransportCore/Documentation.docc/Documentation.md
new file mode 100644
index 0000000..58366b2
--- /dev/null
+++ b/Sources/GRPCNIOTransportCore/Documentation.docc/Documentation.md
@@ -0,0 +1,34 @@
+# ``GRPCNIOTransportCore``
+
+A module containing core components for high-performance HTTP/2 client and server
+transport implementations built on top of SwiftNIO.
+
+## Topics
+
+### Client and server transports
+
+- ``HTTP2ClientTransport``
+- ``HTTP2ServerTransport``
+
+### Transport extensions
+
+- ``ListeningServerTransport``
+
+### Name resolution
+
+- ``ResolvableTarget``
+- ``ResolvableTargets``
+- ``NameResolvers``
+- ``NameResolverRegistry``
+- ``NameResolverFactory``
+- ``NameResolver``
+- ``NameResolutionResult``
+
+### Addresses
+
+- ``SocketAddress``
+- ``Endpoint``
+
+### TLS
+
+- ``TLSConfig``
diff --git a/Sources/GRPCNIOTransportCore/Server/Connection/ServerConnection.swift b/Sources/GRPCNIOTransportCore/Server/Connection/ServerConnection.swift
index 097085c..834ca9d 100644
--- a/Sources/GRPCNIOTransportCore/Server/Connection/ServerConnection.swift
+++ b/Sources/GRPCNIOTransportCore/Server/Connection/ServerConnection.swift
@@ -17,8 +17,8 @@
 package import GRPCCore
 package import NIOCore
 
-public enum ServerConnection {
-  public enum Stream {
+package enum ServerConnection {
+  package enum Stream {
     package struct Outbound: ClosableRPCWriterProtocol {
       package typealias Element = RPCResponsePart<GRPCNIOTransportBytes>