Merge pull request #73 from nodes-vapor/tn-finish-docs

Add missing docs

.gitignore

@@ -6,3 +6,4 @@ Packages
 DerivedData/
 Package.resolved
 .swiftpm
+Tests/LinuxMain.swift

Sources/Bugsnag/BugsnagConfiguration.swift

@@ -1,12 +1,24 @@
+/// Bugsnag's configuration options. 
+///
+///     app.bugsnag.configuration = .init(...)
+///
 public struct BugsnagConfiguration {
+    /// Notifier API key found in Bugsnag project settings.
     public var apiKey: String
+
+    /// Which version of your app is running, like `development` or `production`.
     public var releaseStage: String
 
     /// A version identifier, (eg. a git hash)
     public var version: String?
+
+    /// Defines sensitive keys that should be hidden from data reported to Bugsnag.
     public var keyFilters: Set<String>
+
+    /// Controls whether reports are sent to Bugsnag.
     public var shouldReport: Bool
 
+    /// Creates a new `BugsnagConfiguration`.
     public init(
         apiKey: String,
         releaseStage: String,

Sources/Bugsnag/BugsnagMiddleware.swift

@@ -1,10 +1,16 @@
 import Vapor
 
+/// Automatically catches and reports errors to Bugsnag.
+///
+///     app.middleware.use(BugsnagMiddleware())
+///
+/// This should be placed _before_ `ErrorMiddleware`. 
 public struct BugsnagMiddleware {
     public init() { }
 }
 
 extension BugsnagMiddleware: Middleware {
+    /// See `Middleware`.
     public func respond(to request: Request, chainingTo next: Responder) -> EventLoopFuture<Response> {
         next.respond(to: request).flatMapErrorThrowing { error in
             request.bugsnag.report(error)

Sources/Bugsnag/BugsnagReporter.swift

@@ -1,16 +1,40 @@
 import class Foundation.JSONSerialization
 import Vapor
 
+/// Capable of reporting Bugsnag errors.
+///
+/// See `req.bugsnag` and `app.bugsnag`.
 public protocol BugsnagReporter {
+    /// HTTP client used to contact Bugsnag.
     var client: Client { get }
+
+    /// Logger to use for reporting information or errors.
     var logger: Logger { get }
+
+    /// EventLoop to use for future returns.
     var eventLoop: EventLoop { get }
+
+    /// Bugsnag configuration options for reporting.
     var configuration: BugsnagConfiguration? { get }
+
+    /// Used to include additional information about the current
+    /// request in the report. 
     var currentRequest: Request? { get }
+
+    /// Configures which users will be reported by Bugsnag.
     var users: BugsnagUsers { get }
 }
 
 extension BugsnagReporter {
+    /// Reports an error to Bugsnag.
+    ///
+    ///     req.bugsnag.report(someError)
+    ///
+    /// Conformance to `DebuggableError` and `BugsnagError` will be checked 
+    /// for additional error context. 
+    ///
+    /// - parameters:
+    ///     - error: The error to report. 
     @discardableResult
     public func report(
         _ error: Error

Sources/Bugsnag/Request+Bugsnag.swift

@@ -1,16 +1,34 @@
 import Vapor
 
 extension Request {
+    /// Bugsnag helper. Used to send reports during route handling.
+    ///
+    ///     // Report an error.
+    ///     req.bugsnag.report(someError)
+    ///
     public var bugsnag: Bugsnag {
         .init(request: self)
     }
 
+    /// Bugsnag helper. Used to send reports during route handling.
+    ///
+    ///     // Report an error.
+    ///     req.bugsnag.report(someError)
+    ///
     public struct Bugsnag {
         public let request: Request
     }
 }
 
 extension Request.Bugsnag {
+    /// Adds a breadcrumb to all reports sent.
+    ///
+    ///     req.bugsnag.breadcrumb("login", type: .user)
+    ///
+    /// - parameters:
+    ///     - name: Unique identifier for this breadcrumb.
+    ///     - type: Type of breadcrumb. 
+    ///     - metadata: Optional context dictionary.
     @discardableResult
     public func breadcrumb(
         name: String,
@@ -50,31 +68,38 @@ extension Request.Bugsnag {
 }
 
 extension Request.Bugsnag: BugsnagReporter {
+    /// See `BugsnagReporter`.
     public var currentRequest: Request? {
         self.request
     }
 
+    /// See `BugsnagReporter`.
     public var client: Client {
         self.request.client
     }
 
+    /// See `BugsnagReporter`.
     public var logger: Logger {
         self.request.logger
     }
 
+    /// See `BugsnagReporter`.
     public var eventLoop: EventLoop {
         self.request.eventLoop
     }
 
+    /// See `BugsnagReporter`.
     public var configuration: BugsnagConfiguration? {
         self.request.application.bugsnag.configuration
     }
 
+    /// See `BugsnagReporter`.
     public var users: BugsnagUsers {
         self.request.application.bugsnag.users
     }
 }
 
+/// Types of Bugsnag report breadcrumbs. 
 public enum BugsnagBreadcrumbType: String {
     case error
     case log

Sources/Bugsnag/Severity.swift

@@ -1,6 +1,12 @@
+/// Error severity. See `BugsnagError`.
 public struct BugsnagSeverity {
+    /// Information.
     public static let info = Self(value: "info")
+
+    /// Warning.
     public static let warning = Self(value: "warning")
+
+    /// Error.
     public static let error = Self(value: "error")
 
     let value: String