Update Jazzy docs with handler example and other minor improvements (#59)

Author: seabaylea

.jazzy.yaml

@@ -20,8 +20,8 @@ custom_categories:
     children:
     - HTTPServer
     - HTTPServing
-    - HTTPRequestHandling
     - HTTPRequestHandler
+    - HTTPRequestHandling
 
   - name: HTTP Headers
     children:

Sources/HTTP/HTTPCommon.swift

@@ -9,40 +9,39 @@
 import Foundation
 
 /// Typealias for a closure that handles an incoming HTTP request
-/// - Parameter req: the incoming HTTP request.
-/// - Parameter res: a writer providing functions to create an HTTP reponse to the request.
-/// - Returns HTTPBodyProcessing: a enum that either discards the request data, or provides a closure to process it.
-/// - See: `HTTPRequestHandling` for more information
-public typealias HTTPRequestHandler = (HTTPRequest, HTTPResponseWriter) -> HTTPBodyProcessing
-
-/// Class protocol containing the HTTPRequestHandler that responds to the incoming HTTP requests.
-/// The following is an example of a HTTPRequestHandler that returns the request as a response:
-///
+/// The following is an example of an echo `HTTPRequestHandler` that returns the request it receives as a response:
 /// ```swift
-///    class EchoHandler: HTTPRequestHandling {
-///        func handle(request: HTTPRequest, response: HTTPResponseWriter ) -> HTTPBodyProcessing {
-///            res.writeHeader(status: .ok, headers: [:])
-///            return .processBody { (chunk, stop) in
-///                switch chunk {
-///                case .chunk(let data, let finishedProcessing):
-///                    res.writeBody(data) { _ in
-///                        finishedProcessing()
-///                    }
-///                case .end:
-///                    res.done()
-///                default:
-///                    stop = true
-///                    res.abort()
+///    func echo(request: HTTPRequest, response: HTTPResponseWriter ) -> HTTPBodyProcessing {
+///        response.writeHeader(status: .ok)
+///        return .processBody { (chunk, stop) in
+///            switch chunk {
+///            case .chunk(let data, let finishedProcessing):
+///                response.writeBody(data) { _ in
+///                    finishedProcessing()
 ///                }
+///            case .end:
+///                response.done()
+///            default:
+///                stop = true
+///                response.abort()
 ///            }
 ///        }
 ///    }
 /// ```
+/// This then needs to be registered with the server using `HTTPServer.start(port:handler:)`
+/// - Parameter req: the incoming HTTP request.
+/// - Parameter res: a writer providing functions to create an HTTP reponse to the request.
+/// - Returns HTTPBodyProcessing: a enum that either discards the request data, or provides a closure to process it.
+public typealias HTTPRequestHandler = (HTTPRequest, HTTPResponseWriter) -> HTTPBodyProcessing
+
+/// Class protocol containing a `handle()` function that implements `HTTPRequestHandler` to respond to incoming HTTP requests.
+/// - See: `HTTPRequestHandler` for more information
 public protocol HTTPRequestHandling: class {
-    /// handle: function called when a new HTTP request is received by the HTTP server.
+    /// handle: function that implements `HTTPRequestHandler` and is called when a new HTTP request is received by the HTTP server.
     /// - Parameter request: the incoming HTTP request.
     /// - Parameter response: a writer providing functions to create an HTTP response to the request.
     /// - Returns HTTPBodyProcessing: a enum that either discards the request data, or provides a closure to process it.
+    /// - See: `HTTPRequestHandler` for more information
     func handle(request: HTTPRequest, response: HTTPResponseWriter) -> HTTPBodyProcessing
 }
 

Sources/HTTP/HTTPRequest.swift

@@ -21,9 +21,9 @@ public struct HTTPRequest {
     public var headers: HTTPHeaders
 }
 
-/// Method that takes a chunk of request body and is expected to write to the ResponseWriter
+/// Method that takes a chunk of request body and is expected to write to the `HTTPResponseWriter`
 /// - Parameter HTTPBodyChunk: `HTTPBodyChunk` representing some or all of the incoming request body
-/// - Parameter Bool: Bool that can be set to true in order to prevent further processing
+/// - Parameter Bool: A boolean flag that can be set to true in order to prevent further processing
 public typealias HTTPBodyHandler = (HTTPBodyChunk, inout Bool) -> Void
 
 /// Indicates whether the body is going to be processed or ignored

Sources/HTTP/HTTPServer.swift

@@ -28,11 +28,11 @@ public protocol HTTPServing : class {
 public class HTTPServer: HTTPServing {
     private let server = PoCSocketSimpleServer()
 
-    /// Create an instance of the server. This needs to be followed with a call to `start()`
+    /// Create an instance of the server. This needs to be followed with a call to `start(port:handler:)`
     public init() {
     }
 
-    /// Start the HTTP server on the given `port`, using `handler` to process incoming requests
+    /// Start the HTTP server on the given `port` number, using a `HTTPRequestHandler` to process incoming requests.
     public func start(port: Int = 0, handler: @escaping HTTPRequestHandler) throws {
         try server.start(port: port, handler: handler)
     }
@@ -42,7 +42,7 @@ public class HTTPServer: HTTPServing {
         server.stop()
     }
 
-    /// The port the server is listening on
+    /// The port number the server is listening on
     public var port: Int {
         return server.port
     }