docs updates

.gitignore

@@ -2,3 +2,5 @@
 /.build
 /Packages
 /*.xcodeproj
+Package.resolved
+

Package.swift

@@ -11,7 +11,7 @@ let package = Package(
         .package(url: "https://github.com/vapor/core.git", from: "3.0.0"),
 
         // 🚀 Non-blocking, event-driven HTTP for Swift built on Swift NIO.
-        .package(url: "https://github.com/vapor/http.git", .branch("gm")),
+        .package(url: "https://github.com/vapor/http.git", .branch("master")),
 
         // Event-driven network application framework for high performance protocol servers & clients, non-blocking.
         .package(url: "https://github.com/apple/swift-nio.git", from: "1.4.0"),

Sources/WebSocket/WebSocket+Client.swift

@@ -1,13 +1,23 @@
+/// Allows `HTTPClient` to be used to create `WebSocket` connections.
+///
+///     let ws = try HTTPClient.webSocket(hostname: "echo.websocket.org", on: ...).wait()
+///     ws.onText { ws, text in
+///         print("server said: \(text)")
+///     }
+///     ws.send("Hello, world!")
+///     try ws.onClose.wait()
+///
 extension HTTPClient {
-    /// Performs an HTTP protocol upgrade to WebSocket protocol `HTTPClient`.
+    // MARK: Client Upgrade
+
+    /// Performs an HTTP protocol upgrade to` WebSocket` protocol `HTTPClient`.
     ///
-    ///     let worker = MultiThreadedEventLoopGroup(numThreads: 1)
-    ///     let webSocket = try HTTPClient.webSocket(hostname: "echo.websocket.org", on: worker).wait()
-    ///     webSocket.onText { ws, text in
-    ///         print("server said: \(text))
+    ///     let ws = try HTTPClient.webSocket(hostname: "echo.websocket.org", on: ...).wait()
+    ///     ws.onText { ws, text in
+    ///         print("server said: \(text)")
     ///     }
-    ///     webSocket.send("Hello, world!")
-    ///     try webSocket.onClose.wait()
+    ///     ws.send("Hello, world!")
+    ///     try ws.onClose.wait()
     ///
     /// - parameters:
     ///     - scheme: Transport layer security to use, either tls or plainText.

Sources/WebSocket/WebSocket+Server.swift

@@ -1,8 +1,27 @@
-extension WebSocket {
-    /// Creates an `HTTPProtocolUpgrader` that will create instances of this class upon HTTP upgrade.
+/// Allows `HTTPServer` to accept `WebSocket` connections.
+///
+///     let ws = HTTPServer.webSocketUpgrader(shouldUpgrade: { req in
+///         // return non-nil HTTPHeaders to allow upgrade
+///     }, onUpgrade: { ws, req in
+///         // setup callbacks or send data to connected WebSocket
+///     })
+///
+///     HTTPServer.start(..., upgraders: [ws])
+///
+extension HTTPServer {
+    // MARK: Server Upgrade
+
+    /// Creates an `HTTPProtocolUpgrader` that will accept incoming `WebSocket` upgrade requests.
     ///
-    /// Use this with `HTTPServer.start(...)`.
-    public static func httpProtocolUpgrader(
+    ///     let ws = HTTPServer.webSocketUpgrader(shouldUpgrade: { req in
+    ///         // return non-nil HTTPHeaders to allow upgrade
+    ///     }, onUpgrade: { ws, req in
+    ///         // setup callbacks or send data to connected WebSocket
+    ///     })
+    ///
+    ///     HTTPServer.start(..., upgraders: [ws])
+    ///
+    public static func webSocketUpgrader(
         shouldUpgrade: @escaping (HTTPRequest) -> (HTTPHeaders?),
         onUpgrade: @escaping (WebSocket, HTTPRequest) -> ()
     ) -> HTTPProtocolUpgrader {

Sources/WebSocket/WebSocket.swift

@@ -6,19 +6,11 @@
 ///      }
 ///
 public final class WebSocket: BasicWorker {
-    /// `true` if the `WebSocket` has been closed.
-    public private(set) var isClosed: Bool
-
     /// See `BasicWorker`.
     public var eventLoop: EventLoop {
         return channel.eventLoop
     }
 
-    /// A `Future` that will be completed when the `WebSocket` closes.
-    public var onClose: Future<Void> {
-        return channel.closeFuture
-    }
-
     /// Outbound `WebSocketEventHandler`.
     private let channel: Channel
 
@@ -41,6 +33,8 @@ public final class WebSocket: BasicWorker {
         self.onErrorCallback = { _, _ in }
     }
 
+    // MARK: Receive
+
     /// Adds a callback to this `WebSocket` to receive text-formatted messages.
     ///
     ///     ws.onText { ws, string in
@@ -83,6 +77,8 @@ public final class WebSocket: BasicWorker {
         onErrorCallback = callback
     }
 
+    // MARK: Send
+
     /// Sends text-formatted data to the connected client.
     ///
     ///     ws.onText { ws, string in
@@ -135,6 +131,16 @@ public final class WebSocket: BasicWorker {
         send(binary, opcode: .binary, promise: promise)
     }
 
+    // MARK: Close
+
+    /// `true` if the `WebSocket` has been closed.
+    public private(set) var isClosed: Bool
+
+    /// A `Future` that will be completed when the `WebSocket` closes.
+    public var onClose: Future<Void> {
+        return channel.closeFuture
+    }
+
     /// Closes the `WebSocket`'s connection, disconnecting the client.
     public func close() {
         guard !isClosed else {