Update the API documentation for Kitura (#719)

* #706 Documented ParsedBody and Part * #706 Updated .jazzy.yml to 08/23 driver * #706 Updated doc for Kitura.swift * #706 Improved documentation of ParsedBody and Part * #706 Updated documentation of HTTPVersion, JSONPError, LinkParameter and BodyParser * #706 Added documentation for various files * #706 Documentation fixes * #706 Minor hack to get the RouterHAndler documentation included * #706 Fixed documentation made initializer public of a public class * #706 Update API docs * #706 Fixed compile errors. * #706 Added documentation to the router verbs generator and generated code * #706 Documented the error functions of Router * #706 Changes after review. * #706 Corrected English * #706 Corrected English * #706 Regenerated the API documentation HTML files.
Kitura · Sep 5, 2016 · 4b49282 · 4b49282
1 parent 3a102e8
commit 4b49282
Show file tree

Hide file tree

Showing 81 changed files with 20,024 additions and 2,046 deletions.
diff --git a/.jazzy.yaml b/.jazzy.yaml
@@ -11,5  11,5 @@ readme: README.md
 skip_undocumented: false
 hide_documentation_coverage: false
 
-xcodebuild_arguments: [-project, Kitura.xcodeproj, -target, Kitura, -toolchain, org.swift.3020160725a, LIBRARY_SEARCH_PATHS=.build/debug]
 xcodebuild_arguments: [-project, Kitura.xcodeproj, -target, Kitura, -toolchain, org.swift.3020160823a, LIBRARY_SEARCH_PATHS=.build/debug]
 
diff --git a/Scripts/generate_router_verbs.sh b/Scripts/generate_router_verbs.sh
@@ -43,24  43,68 @@ EOF
 
 for VERB in `sed '/^$/d' ${INPUT_FILE} | sed '/^#/d'`; do
 VERB_LOW_CASE=`echo $VERB | cut -c1 | tr '[:upper:]' '[:lower:]'``echo $VERB | cut -c2-`
 VERB_UPPER_CASE=`echo $VERB | tr '[:lower:]' '[:upper:]'`
 if [ "${VERB_UPPER_CASE}" == "ALL" ]; then
   DOC_TEXT_1="any" 
   DOC_TEXT_2=""
 else
   DOC_TEXT_1="HTTP $VERB_UPPER_CASE"
   DOC_TEXT_2="s"
 fi
 cat <<EOF >> ${OUTPUT_FILE}
     // MARK: $VERB
 
     /// Setup a set of one or more closures of the type \`RouterHandler\` that will be
     /// invoked when $DOC_TEXT_1 request$DOC_TEXT_2 comes to the server. If a path pattern is
     /// specified, the handlers will only be invoked if the pattern is matched.
     ///
     /// - Parameter path: An optional String specifying the pattern that needs to be
     ///                  matched, in order for the handlers to be invoked.
     /// - Parameter handler: A comma delimited set of \`RouterHandler\`s that will be
     ///                     invoked when $DOC_TEXT_1 request$DOC_TEXT_2 comes to the server.
     @discardableResult
     public func $VERB_LOW_CASE(_ path: String?=nil, handler: @escaping RouterHandler...) -> Router {
         return routingHelper(.$VERB_LOW_CASE, pattern: path, handler: handler)
     }
 
     /// Setup an array of one or more closures of the type \`RouterHandler\` that will be
     /// invoked when $DOC_TEXT_1 request$DOC_TEXT_2 comes to the server. If a path pattern is
     /// specified, the handlers will only be invoked if the pattern is matched.
     ///
     /// - Parameter path: An optional String specifying the pattern that needs to be
     ///                  matched, in order for the handlers to be invoked.
     /// - Parameter handler: The array of \`RouterHandler\`s that will be
     ///                     invoked when $DOC_TEXT_1 request$DOC_TEXT_2 comes to the server.
     @discardableResult
     public func $VERB_LOW_CASE(_ path: String?=nil, handler: [RouterHandler]) -> Router {
         return routingHelper(.$VERB_LOW_CASE, pattern: path, handler: handler)
     }
 
     /// Setup a set of one or more \`RouterMiddleware\` that will be
     /// invoked when $DOC_TEXT_1 request$DOC_TEXT_2 comes to the server. If a path pattern is
     /// specified, the \`RouterMiddleware\` will only be invoked if the pattern is matched.
     ///
     /// - Parameter path: An optional String specifying the pattern that needs to be
     ///                  matched, in order for the \`RouterMiddleware\` to be invoked.
     /// - Parameter allowPartialMatch: A Bool that indicates whether or not a partial match of
     ///                               the path by the pattern is sufficient.
     /// - Parameter handler: A comma delimited set of \`RouterMiddleware\` that will be
     ///                     invoked when $DOC_TEXT_1 request$DOC_TEXT_2 comes to the server.
     @discardableResult
     public func $VERB_LOW_CASE(_ path: String?=nil, allowPartialMatch: Bool = true, middleware: RouterMiddleware...) -> Router {
         return routingHelper(.$VERB_LOW_CASE, pattern: path, allowPartialMatch: allowPartialMatch, middleware: middleware)
     }
 
     /// Setup an array of one or more \`RouterMiddleware\` that will be
     /// invoked when $DOC_TEXT_1 request$DOC_TEXT_2 comes to the server. If a path pattern is
     /// specified, the \`RouterMiddleware\` will only be invoked if the pattern is matched.
     ///
     /// - Parameter path: An optional String specifying the pattern that needs to be
     ///                  matched, in order for the \`RouterMiddleware\` to be invoked.
     /// - Parameter allowPartialMatch: A Bool that indicates whether or not a partial match of
     ///                               the path by the pattern is sufficient.
     /// - Parameter handler: The array of \`RouterMiddleware\` that will be
     ///                     invoked when $DOC_TEXT_1 request$DOC_TEXT_2 comes to the server.
     @discardableResult
     public func $VERB_LOW_CASE(_ path: String?=nil, allowPartialMatch: Bool = true, middleware: [RouterMiddleware]) -> Router {
         return routingHelper(.$VERB_LOW_CASE, pattern: path, allowPartialMatch: allowPartialMatch, middleware: middleware)

diff --git a/Sources/Kitura/HTTPVersion.swift b/Sources/Kitura/HTTPVersion.swift
@@ -14,7  14,16 @@
  * limitations under the License.
  */
 
 // MARK HttpVersion
 
 /// The version of HTTP protocol.
 ///
 /// HTTP uses a "major.minor" numbering scheme to indicate versions of the protocol.
 public struct HTTPVersion {
 
     /// The "major" part of the protocol version.
     public let major: UInt16
 
     /// The "minor" part of the protocol version.
     public let minor: UInt16
 }
diff --git a/Sources/Kitura/Headers.swift b/Sources/Kitura/Headers.swift
@@ -17,41  17,51 @@
 import Foundation
 import KituraNet
 
-/// Headers
 /// The struct containing the HTTP headers and implements the headers APIs for the
 /// `RouterRequest` and `RouterResponse` classes.
 public struct Headers {
 
     /// The header storage
     internal var headers: HeadersContainer
 
-    /// Initialize a `Headers`
     /// Initialize a `Headers` instance
     ///
-    /// - Parameter headers: the container for the headers
     /// - Parameter headers: The container for the headers
     init(headers: HeadersContainer) {
         self.headers = headers
     }
 
     /// Append values to the header
     ///
-    /// - Parameter key: the key
-    /// - Parameter value: the value
     /// - Parameter key: The key of the header to append a value to.
     /// - Parameter value: The value to be appended to the specified header.
     public mutating func append(_ key: String, value: String) {
         headers.append(key, value: value)
     }
 }
 
-/// Conformance to `Collection`
 /// Conformance to the `Collection` protocol
 extension Headers: Collection {
 
     /// The starting index of the `Headers` collection
     public var startIndex: HeadersIndex {
         return headers.startIndex
     }
 
     /// The ending index of the `Headers` collection
     public var endIndex: HeadersIndex {
         return headers.endIndex
     }
 
     /// The type of an Index of the `Headers` collection.
     public typealias HeadersIndex = DictionaryIndex<String, [String]>
 
 
     /// Get the value of a HTTP header
     ///
     /// - Parameter key: The HTTP header key whose value is to be retrieved
     ///
     /// - Returns: The value of the specified HTTP header, or nil, if it doesn't exist.
     public subscript(key: String) -> String? {
         get {
             return headers[key]?.first
@@ -66,24  76,35 @@ extension Headers: Collection {
         }
     }
 
     /// Get a (key value) tuple from the `Headers` collection at the specified position.
     ///
     /// - Parameter position: The position in the `Headers` collection of the (key, value)
     ///                      tuple to return.
     ///
     /// - Returns: A (key, value) tuple.
     public subscript(position: HeadersIndex) -> (String, String?) {
         get {
             let (key, value) = headers[position]
             return (key, value.first)
         }
     }
 
     /// Get the next Index in the `Headers` collection after the one specified.
     ///
     /// - Parameter after: The Index whose successor is to be returned.
     ///
     /// - Returns: The Index in the `Headers` collection after the one specified.
     public func index(after i: HeadersIndex) -> HeadersIndex {
         return headers.index(after: i)
     }
 }
 
-/// Various helper methods
 /// Various convenience methods for setting various HTTP headers
 extension Headers {
 
-    /// Sets the location path
     /// Sets the Location HTTP header
     ///
-    /// - Parameter path: the path
     /// - Parameter path: the path to set into the header or the special reserved word "back".
     public mutating func setLocation(_ path: String) {
         var p = path
         if  p == "back" {
@@ -98,8  119,8 @@ extension Headers {
 
     /// Sets the Content-Type HTTP header
     ///
-    /// - Parameter type: the type to set to
-    /// - Parameter charset: the charset to specify
     /// - Parameter type: The type to set in the Content-Type header
     /// - Parameter charset: The charset to specify in the Content-Type header.
     public mutating func setType(_ type: String, charset: String? = nil) {
         if  let contentType = ContentType.sharedInstance.getContentType(forExtension: type) {
             var contentCharset = ""
@@ -110,10  131,11 @@ extension Headers {
         }
     }
 
-    /// Sets the Content-Disposition to "attachment" and optionally
-    /// sets filename parameter in Content-Disposition and Content-Type
     /// Sets the HTTP header Content-Disposition to "attachment", optionally
     /// adding the filename parameter. If a file is specified the HTTP header
     /// Content-Type will be set based on the extension of the specified file.
     ///
-    /// - Parameter for: the file to set the filename to
     /// - Parameter for: The file to set the filename to
     public mutating func addAttachment(for filePath: String? = nil) {
         guard let filePath = filePath else {
             self["Content-Disposition"] = "attachment"
@@ -135,7  157,7 @@ extension Headers {
     /// Adds a link with specified parameters to Link HTTP header
     ///
     /// - Parameter link: link value
-    /// - Parameter linkParameters: the link parameters (according to RFC 5988) with their values
     /// - Parameter linkParameters: The link parameters (according to RFC 5988) with their values
     public mutating func addLink(_ link: String, linkParameters: [LinkParameter: String]) {
         var headerValue = "<\(link)>"
 

diff --git a/Sources/Kitura/JSONPError.swift b/Sources/Kitura/JSONPError.swift
@@ -16,11  16,18 @@
 
 import Foundation
 
 // MARK JSONPError
 
 /// An error that can be thrown while handling JSONP.
 public enum JSONPError: Swift.Error {
 
     /// The error thrown if the callback query parameter is invalid.
     case invalidCallbackName(name: String?)
 }
 
 extension JSONPError: CustomStringConvertible {
 
     /// A String representation of the error.
     public var description: String {
         switch self {
         case .invalidCallbackName(let name):

diff --git a/Sources/Kitura/Kitura.swift b/Sources/Kitura/Kitura.swift
@@ -23,13  23,13 @@ import Dispatch
 
 // MARK Kitura
 
-///
 /// A set of helper functions to make it easier to create, start, and stop Kitura based servers.
 public class Kitura {
 
     /// Add an HTTPServer on a port with a delegate.
     ///
     /// The server is only registered with the framework, it does not start listening
-    /// on the port until Kitura.run() is called.
     /// on the port until Kitura.run() or Kitura.start() is called.
     ///
     /// - Parameter onPort: The port to listen on.
     /// - Parameter with: The `ServerDelegate` to use.
@@ -45,11  45,11 @@ public class Kitura {
     /// Add a FastCGIServer on a port with a delegate.
     ///
     /// The server is only registered with the framework, it does not start listening
-    /// on the port until Kitura.run() is called.
     /// on the port until Kitura.run() or Kitura.start() is called.
     ///
     /// - Parameter onPort: The port to listen on.
     /// - Parameter with: The `ServerDelegate` to use.
-    /// - Return: The created `FastCGIServer`.
     /// - Returns: The created `FastCGIServer`.
     @discardableResult
     public class func addFastCGIServer(onPort port: Int, with delegate: ServerDelegate) -> FastCGIServer {
         let server = FastCGI.createServer()
@@ -62,7  62,7 @@ public class Kitura {
     ///
     /// Make all registered servers start listening on their port.
     ///
-    /// - Note: This function never returns - it should be the last call in your main.swift
     /// - note: This function never returns - it should be the last call in your main.swift
     public class func run() {
         Log.verbose("Starting Kitura framework...")
         for (server, port) in httpServersAndPorts {
@@ -93,6  93,8 @@ public class Kitura {
     /// Stop all registered servers
     ///
     /// Make all registered servers stop listening on their port.
     ///
     /// - note: All of the registered servers are unregistered after they are stopped.
     public class func stop() {
         for (server, port) in httpServersAndPorts {
             Log.verbose("Stopping HTTP Server on port \(port)...")

diff --git a/Sources/Kitura/LinkParameter.swift b/Sources/Kitura/LinkParameter.swift
@@ -14,13  14,32 @@
  * limitations under the License.
  */
 
 // MARK LinkParameter
 
 /// Possible parameters of Link HTTP header.
 ///
 /// See [RFC 5988](https://tools.ietf.org/html/rfc5988) for more details.
 public enum LinkParameter: String {
 
     /// The relation type of the link.
     case rel
 
     /// The context of a link conveyed in the Link header field.
     case anchor
 
     /// An indication that the semantics of the relationship are in the reverse direction.
     case rev
 
     /// A hint indicating what the language of the result of dereferencing the link should be.
     case hreflang
 
     /// An intended destination medium or media for style information.
     case media
 
     /// A human-readable label of the destination of a link.
     case title
 
     /// A hint indicating what the media type of the result of dereferencing the link should be.
     case type
 }
 

diff --git a/Sources/Kitura/RouteRegex.swift b/Sources/Kitura/RouteRegex.swift
@@ -19,14  19,17 @@ import LoggerAPI
 
 import Foundation
 
 // MARK RouteRegex
 
 #if os(Linux)
     typealias RegularExpressionType = RegularExpression
 #else
     typealias RegularExpressionType = NSRegularExpression
 #endif
 
-///
 /// A set of helper functions for router path matching using regular expression.
 public class RouteRegex {
     /// A shared instance of RouteRegex.
     public static let sharedInstance = RouteRegex()
 
     private let namedCaptureRegex: RegularExpressionType