     import Glibc
 #endif
 
+/// Special `Error` that may be thrown if we fail to create a `SocketAddress`.
 public enum SocketAddressError: Error {
-    case unknown
+    /// The host is unknown (could not be resolved).
+    case unknown(host: String, port: Int32)
+    /// The requested `SocketAddress` is not supported.
     case unsupported
+    /// The requested UDS path is too long.
     case unixDomainSocketPathTooLong
 }
 
+/// Represent a socket address to which we may want to connect or bind.
 public enum SocketAddress: CustomStringConvertible {
     case v4(address: sockaddr_in, host: String)
     case v6(address: sockaddr_in6, host: String)
     case unixDomainSocket(address: sockaddr_un)
 
+    /// A human-readable description of this `SocketAddress`. Mostly useful for logging.
     public var description: String {
         let port: String
         let host: String?

            throw SocketAddressError.unsupported
        }
    }

}


        }
    }

    /// Creates a new IPV4 `SocketAddress`.
    ///
    /// - parameters:
    ///       - addr: the `sockaddr_in` that holds the ipaddress and port.
    ///       - host: the hostname that resolved to the ipaddress.
    public init(IPv4Address addr: sockaddr_in, host: String) {
        self = .v4(address: addr, host: host)
    }

    /// Creates a new IPV6 `SocketAddress`.
    ///
    /// - parameters:
    ///       - addr: the `sockaddr_in` that holds the ipaddress and port.
    ///       - host: the hostname that resolved to the ipaddress.
    public init(IPv6Address addr: sockaddr_in6, host: String) {
        self = .v6(address: addr, host: host)
    }

    /// Creates a new UDS `SocketAddress`.
    ///
    /// - parameters:
    ///     - path: the path to use for the `SocketAddress`.
    /// - returns: the `SocketAddress` for the given path.
    /// - throws: may throw `SocketAddressError.unixDomainSocketPathTooLong` if the path is too long.
    public static func unixDomainSocketAddress(path: String) throws -> SocketAddress {
        guard path.utf8.count <= 103 else {
            throw SocketAddressError.unixDomainSocketPathTooLong
