Update README.md and Jazzy annotations (swift-server#43)

Author: seabaylea

.jazzy.yaml

@@ -18,6 +18,8 @@ custom_categories:
 
  - name: HTTP Server
  children:
+ - HTTPServer
+ - HTTPServing
  - HTTPRequestHandling
  - HTTPRequestHandler
 

README.md

@@ -1,3 +1,74 @@
-# SwiftServerHttp
+# Swift Server Project HTTP APIs
 
-Sample prototype implementation of @weissi's HTTP Sketch v2 from https://lists.swift.org/pipermail/swift-server-dev/Week-of-Mon-20170403/000422.html for discussion.
+This is an early implementation of the Swift Server Project's HTTP APIs. This provides simple HTTP server on which rich web application frameworks can be built.
+
+## Getting Started
+
+
+### Hello World
+The following code implements a very simple "Hello World!" server:
+
+```swift
+import Foundation
+import HTTP
+
+func hello(request: HTTPRequest, response: HTTPResponseWriter ) -> HTTPBodyProcessing { 
+ response.writeHeader(status: .ok) 
+ response.writeBody("Hello, World!") 
+ response.done() 
+ return .discardBody 
+} 
+
+let server = HTTPServer()
+try! server.start(port: 8080, handler: hello)
+
+CFRunLoopRun()
+```
+
+The `hello()` function receives a `HTTPRequest` that describes the request and a `HTTPResponseWriter` used to write a response. 
+
+Data that is received as part of the request body is made available to the closure that is returned by the `hello()` function. In the "Hello World!" example the request body is not used, so `.discardBody` is returned.
+
+### Echo Server
+The following code implements a very simple Echo server that responds with the contents of the incoming request:
+
+```swift
+import Foundation
+import HTTP
+
+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()
+ }
+ }
+}
+
+let server = HTTPServer()
+try! server.start(port: 8080, handler: echo)
+
+CFRunLoopRun()
+```
+As the Echo server needs to process the request body data and return it in the reponse, the `echo()` function returns a `.processBody` closure. This closure is called with `.chunk` when data is available for processing from the request, and `.end` when no more data is available.
+
+Once any data chunk has been processed, `finishedProcessing()` should be called to signify that it has been handled.
+
+When the response is complete, `response.done()` should be called.
+
+## API Documentation
+Full Jazzy documentation of the API is available here: 
+<https://swift-server.github.io/http/>
+
+ 
+## Acknowledgements
+This project is based on an inital proposal from @weissi on the swift-server-dev mailing list: 
+<https://lists.swift.org/pipermail/swift-server-dev/Week-of-Mon-20170403/000422.html>

Sources/HTTP/HTTPCommon.swift

@@ -12,6 +12,7 @@ import Foundation
 /// - 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.

Sources/HTTP/HTTPServer.swift

@@ -28,21 +28,26 @@ 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()`
  public init() {
  }
 
+ /// Start the HTTP server on the given `port`, using `handler` to process incoming requests
  public func start(port: Int = 0, handler: @escaping HTTPRequestHandler) throws {
  try server.start(handler: handler)
  }
 
+ /// Stop the server
  public func stop() {
  server.stop()
  }
 
+ /// The port the server is listening on
  public var port: Int {
  return server.port
  }
 
+ /// The number of current connections
  public var connectionCount: Int {
  return server.connectionCount
  }

Sources/HTTP/PoCSocket/PoCSocket.swift

@@ -9,6 +9,7 @@
 import Foundation
 import Dispatch
 
+///:nodoc:
 public enum PoCSocketError: Error {
  case SocketOSError(errno: Int32)
  case InvalidSocketError

Sources/HTTP/PoCSocket/PoCSocketConnectionListener.swift

@@ -9,6 +9,7 @@
 import Foundation
 import Dispatch
 
+///:nodoc:
 public class PoCSocketConnectionListener: ParserConnecting {
 
  ///socket(2) wrapper object

Sources/HTTP/PoCSocket/PoCSocketSimpleServer.swift

@@ -13,6 +13,7 @@ import Foundation
 // MARK: Server
 
 /// An HTTP server that listens for connections on a TCP socket and spawns Listeners to handle them.
+///:nodoc:
 public class PoCSocketSimpleServer: CurrentConnectionCounting {
  /// PoCSocket to listen on for connections
  private let serverSocket: PoCSocket = PoCSocket()