Updated documentation style for jazzy

conqueror · conqueror · commit 26a3503ba1b9 · 2018-05-17T13:04:48.000-04:00
diff --git a/Sources/ApplicationConfiguration/AppProtocol.swift b/Sources/ApplicationConfiguration/AppProtocol.swift
@@ -3,18 +3,22 @@ import Foundation
 import PerfectHTTPServer
 import PerfectHTTP
 
-/// A protocol to define Applications
-/// name: application name
-/// config: application configuration
-/// routes: a group of routes
-/// filters: application filters (request & response)
-/// init: to initialize the Application
-/// server to return the server object
+/**
+ A protocol to define Applications
+ It is already implemented by Application
+ - see also: Application
+*/
 public protocol AppProtocol {
+    /// application name
     var name: String { get }
+    /// application configuration
     var config: Configuration? { get}
+    /// a group of routes
     var routes: Routes? { get }
+    /// application filters (request & response)
     var filters: AppFilters? { get }
+    /// initialize the Application
     init(name: String, path: String)
+    /// to return the server object
     func server() -> HTTPServer.Server
 }
diff --git a/Sources/ApplicationConfiguration/Application.swift b/Sources/ApplicationConfiguration/Application.swift
@@ -4,56 +4,72 @@ import PerfectLib
 import PerfectHTTPServer
 import PerfectHTTP
 
-/// This struct represnts an Application
-/// with its configuration, routes and filters
-/// You could use this application or create another
-/// Application object that complies with AppProtocol
+/**
+ This struct represnts an Application
+ with its configuration, routes and filters
+ You could use this application or create another
+ Application object that complies with AppProtocol
+ - see also: AppProtocol
+*/
 public struct Application: AppProtocol {
-    
+    /// Application name
     public var name: String
+    /// Application routes
     public var routes: Routes?
+    /// Application configuration
     public var config: Configuration?
+    /// Application filters
     public var filters: AppFilters?
-    /// init with only name and configuration file path
-    /// - parameter name: application name
-    /// - parameter path: confuration file path - a json file that represents the configs such as:
-    /// {
-    ///     "server": {
-    ///         "baseURL": "localhost:8181",
-    ///         "baseDomain": "localhost",
-    ///         "port": 8181,
-    ///         "secure": 0
-    ///     },
-    ///     "os": 2,
-    ///     "environment": 1,
-    ///     "ssl": {
-    ///         "port": 443,
-    ///         "originCertificatePath": "",
-    ///         "privateKeyPath": "",
-    ///         "verifyMode": "peer"
-    ///     },
-    ///     "logging": {
-    ///         "requestLoggingPath": "./perfectRequests.log",
-    ///         "logPath": "./perfect.log"
-    ///     },
-    ///     "db": {
-    ///         "name": "perfect",
-    ///         "host": "localhost",
-    ///         "port": 3306,
-    ///         "user": "",
-    ///         "pass": "",
-    ///         "driverType": 1
-    ///     }
-    /// }
+    /**
+     init with only name and configuration file path
+     - parameters:
+        - name: application name
+        - path: confuration file path - a json file that represents the configs
+     ### Example configuration JSON:
+     ````
+     {
+         "server": {
+             "baseURL": "localhost:8181",
+             "baseDomain": "localhost",
+             "port": 8181,
+             "secure": 0
+         },
+         "os": 2,
+         "environment": 1,
+         "ssl": {
+             "port": 443,
+             "originCertificatePath": "",
+             "privateKeyPath": "",
+             "verifyMode": "peer"
+         },
+         "logging": {
+             "requestLoggingPath": "./perfectRequests.log",
+             "logPath": "./perfect.log"
+         },
+         "db": {
+             "name": "perfect",
+             "host": "localhost",
+             "port": 3306,
+             "user": "",
+             "pass": "",
+             "driverType": 1
+         }
+     }
+     ````
+    */
     public init(name: String, path: String) {
         self.init(name: name, path: path, routes: nil, filters: nil)
         self.name = name
     }
-    /// init with name, path, routes and filters
-    /// - parameter name: application name
-    /// - parameter path: confuration file path - a json file that represents the configs
-    /// - parameter routes: a group of routes
-    /// - parameter filters: application filters (request & response)
+    
+    /**
+    init with name, path, routes and filters
+     - parameters:
+        - name: application name
+        - path: confuration file path - a json file that represents the configs
+        - routes: a group of routes
+        - filters: application filters (request & response)
+    */
     public init(name: String,
                 path: String,
                 routes: Routes?,
@@ -86,7 +102,11 @@ public struct Application: AppProtocol {
             self.filters = nil
         }
     }
-    /// return configured server
+    
+    /**
+     Configure and return the server
+     - Returns: HTTPServer.Server
+    */
     public func server() -> HTTPServer.Server {
         
         let port = config?.server?.port ?? 8181
diff --git a/Sources/ApplicationConfiguration/Configuration.swift b/Sources/ApplicationConfiguration/Configuration.swift
@@ -1,24 +1,25 @@
 
 import Foundation
-
-/// This struct represents the configuration of
-/// an application
-/// example usage:
-/// // path represents a json file location that have the same key names as the struct props
-/// let file = File(path)
-/// if file.exists == false {
-///     print("Configuration file doesn't exist!")
-/// }
-/// do {
-///     try file.open(.read, permissions: .readUser)
-///     defer { file.close() }
-///     let json = try file.readString()
-///     let conf = try Configuration(json)
-///     app.config = conf // assign it to your application's config to be used when you launch the server
-/// } catch {
-///     print(error)
-/// }
-
+/**
+ This struct represents the configuration of an application
+ ### Example usage: ###
+ ````
+ // path represents a json file location that have the same key names as the struct props
+ let file = File(path)
+ if file.exists == false {
+     print("Configuration file doesn't exist!")
+ }
+ do {
+     try file.open(.read, permissions: .readUser)
+     defer { file.close() }
+     let json = try file.readString()
+     let conf = try Configuration(json)
+     app.config = conf // assign it to your application's config to be used when you launch the server
+ } catch {
+     print(error)
+ }
+ ````
+*/
 public struct Configuration: Codable {
     /// server configuration including url and port
     let server: ServerConfiguration?
@@ -35,31 +36,59 @@ public struct Configuration: Codable {
     let environment: Environment?
 }
 
-/// This struct represents the server configuration
+/**
+ This struct represents the server configuration
+*/
 public struct ServerConfiguration: Codable {
+    /// base URL
     let baseURL: String?
+    /// base domain
     let baseDomain: String?
+    /// port
     let port: Int?
+    /// if it is a https server 1 else 0
     let secure: Int?
 }
 
-/// configuration for logging
+/**
+ configuration for logging
+*/
 public struct LoggingConfiguration: Codable {
+    /// logging path for requests
     let requestLoggingPath: String?
+    /// logging path
     let logPath: String?
 }
 
-/// database configuration that should be initialized when Configuration is initialized
-/// ScantORM uses this configuration to initialize the DatabaseAdapter
-/// You can use it without ScantORM if you need to
+/**
+ database configuration that should be initialized when Configuration is initialized.
+ **ScantORM** uses this configuration to initialize the DatabaseAdapter.
+ You can use it without ScantORM if you need to!
+*/
 public struct DBConfiguration: Codable {
+    /// database name
     public let name: String?
+    /// host url
     public let host: String?
+    /// port
     public let port: Int?
+    /// database user name
     public let user: String?
+    /// database password
     public let pass: String?
+    /// database driver type
     public let driverType: DBDriverType
     
+    /**
+     initialize the database configuration
+     - parameters:
+        - name: database name
+        - host: host url
+        - port: port address
+        - user: user name
+        - pass: password
+        - driverType: database driver type such as mySQL
+    */
     public init(name: String?,
                 host: String?,
                 port: Int?,
@@ -75,36 +104,57 @@ public struct DBConfiguration: Codable {
     }
 }
 
-/// Database driver type
+/**
+ Database driver type
+*/
 public enum DBDriverType: Int, Codable {
+    /// MySQL
     case mySQL = 1
+    /// PostgreSQL
     case postgreSQL = 2
+    /// SQLite
     case sqLite = 3
 }
 
-/// SSL configuration for https server
+/**
+ SSL configuration for https server
+*/
 public struct SSLConfiguration: Codable {
+    /// https port
     let port: Int?
+    /// origin certificate path
     let originCertificatePath: String?
+    /// private key path
     let privateKeyPath: String?
+    /// verify mode
     let verifyMode: String?
 }
 
-/// operating system
+/**
+ operating system
+*/
 public enum OS: Int, Codable {
+    /// Linux
     case linux = 1
+    /// macOS
     case macOS = 2
 }
 
-/// deployment environment
+/**
+ deployment environment
+*/
 public enum Environment: Int, Codable {
+    /// development environment
     case dev = 1
+    /// pre production environment
     case preProd = 2
+    /// production environment
     case prod = 3
 }
 
 // MARK: Convenience initializers
 
+
 extension Configuration {
     /// init configuration with Data
     public init(data: Data) throws {
