Add jazzy config, build docs in CI, and clean up documentation comments. (#17)

Author: gwhelanLD

.circleci/config.yml

@@ -57,6 +57,12 @@ jobs:
         command: swift test -v 2>&1 | tee 'artifacts/raw-logs-swiftpm.txt' | xcpretty -r junit -o 'test-results/swiftpm/junit.xml'
         when: always
 
+    - run:
+        name: Build Documentation
+        command: |
+          sudo gem install jazzy
+          jazzy -o artifacts/docs
+
     - store_test_results:
         path: test-results
 

.gitignore

@@ -5,4 +5,5 @@
 /.build
 xcuserdata/
 IDEWorkspaceChecks.plist
-.swiftpm
+.swiftpm
+/docs

.jazzy.yaml

@@ -0,0 +1,13 @@
+module: LDSwiftEventSource
+author: LaunchDarkly
+author_url: https://launchdarkly.com
+github_url: https://github.com/launchdarkly/swift-eventsource
+clean: true
+swift_build_tool: spm
+readme: README.md
+documentation:
+  - CHANGELOG.md
+  - CONTRIBUTING.md
+  - LICENSE.txt
+
+copyright: 'Copyright © 2020 Catamorphic Co.'

Source/LDSwiftEventSource.swift

@@ -17,65 +17,68 @@ public class EventSource {
     private let esDelegate: EventSourceDelegate
 
     /**
-     Initialize an EventSource with the given configuration.
+     Initialize the `EventSource` client with the given configuration.
 
-     - Parameter config: The configuration for initializing the EventSource.
+     - Parameter config: The configuration for initializing the `EventSource` client.
      */
     public init(config: Config) {
         esDelegate = EventSourceDelegate(config: config)
     }
 
     /**
-     Start the EventSource object.
+     Start the `EventSource` client.
 
-     This will create a stream connection to the configured URL. The application will be informed of received events
-     and state changes using the configured EventHandler.
+     This will initiate a streaming connection to the configured URL. The application will be informed of received
+     events and state changes using the configured `EventHandler`.
      */
     public func start() {
         esDelegate.start()
     }
 
-    /// Shuts down the EventSource object. It is not valid to restart the EventSource after calling this function.
+    /// Shuts down the `EventSource` client. It is not valid to restart the client after calling this function.
     public func stop() {
         esDelegate.stop()
     }
 
-    /**
-     Get the most recently received event ID, or the configured `lastEventId` if no event IDs have been received.
-     */
+    /// Get the most recently received event ID, or the value of `EventSource.Config.lastEventId` if no event IDs have
+    /// been received.
     public func getLastEventId() -> String? { esDelegate.getLastEventId() }
 
-    /// Struct describing the configuration of the EventSource
+    /// Struct for configuring the EventSource.
     public struct Config {
-        /// The EventHandler called in response to activity on the stream.
+        /// The `EventHandler` called in response to activity on the stream.
         public let handler: EventHandler
-        /// The URL of the request used when connecting to the EventSource API.
+        /// The `URL` of the request used when connecting to the EventSource API.
         public let url: URL
 
-        /// The method to use for the EventSource connection
+        /// The HTTP method to use for the API request.
         public var method: String = "GET"
-        /// Optional body to be sent with the initial request
+        /// Optional HTTP body to be included in the API request.
         public var body: Data?
-        /// Error handler that can determine whether to proceed or shutdown.
-        public var connectionErrorHandler: ConnectionErrorHandler = { _ in .proceed }
-        /// An initial value for the last-event-id to be set on the initial request
+        /// An initial value for the last-event-id header to be sent on the initial request
         public var lastEventId: String?
-        /// Additional headers to be set on the request
+        /// Additional HTTP headers to be set on the request
         public var headers: [String: String] = [:]
-        /// Provides the ability to add conditional headers
+        /// Transform function to allow dynamically configuring the headers on each API request.
         public var headerTransform: HeaderTransform = { $0 }
         /// The minimum amount of time to wait before reconnecting after a failure
         public var reconnectTime: TimeInterval = 1.0
         /// The maximum amount of time to wait before reconnecting after a failure
         public var maxReconnectTime: TimeInterval = 30.0
-        /// The minimum amount of time for an EventSource connection to remain open before allowing connection
+        /// The minimum amount of time for an `EventSource` connection to remain open before allowing the connection
         /// backoff to reset.
         public var backoffResetThreshold: TimeInterval = 60.0
-        /// The maximum amount of time between receiving any data before considering the connection to have
-        /// timed out.
+        /// The maximum amount of time between receiving any data before considering the connection to have timed out.
         public var idleTimeout: TimeInterval = 300.0
 
-        /// Create a new configuration with an EventHandler and a URL
+        /**
+         An error handler that is called when an error occurs and can shut down the client in response.
+
+         The default error handler will always attempt to reconnect on an error, unless `EventSource.stop()` is called.
+         */
+        public var connectionErrorHandler: ConnectionErrorHandler = { _ in .proceed }
+
+        /// Create a new configuration with an `EventHandler` and a `URL`
         public init(handler: EventHandler, url: URL) {
             self.handler = handler
             self.url = url

Source/Types.swift

@@ -1,32 +1,46 @@
 import Foundation
 
-/// Type for a function that will be notified when EventSource encounters a connection failure.
-/// This is different from onError in that it will not be called for other kinds of errors; also,
-/// it has the ability to tell EventSource to stop reconnecting.
+/**
+ Type for a function that will be notified when the `EventSource` client encounters a connection failure.
+
+ This is different from `EventHandler.onError(error:)` in that it will not be called for other kinds of errors; also,
+ it has the ability to tell the client to stop reconnecting by returning a `ConnectionErrorAction.shutdown`.
+*/
 public typealias ConnectionErrorHandler = (Error) -> ConnectionErrorAction
 
-/// Type for a function that will take in the current http headers
-/// and return a new set of http headers to be used when connecting
-/// and reconnecting to a stream.
+/**
+ Type for a function that will take in the current HTTP headers and return a new set of HTTP headers to be used when
+ connecting and reconnecting to a stream.
+ */
 public typealias HeaderTransform = ([String: String]) -> [String: String]
 
-/// Potential actions a ConnectionErrorHandler can return
+/// Potential actions a `ConnectionErrorHandler` can return
 public enum ConnectionErrorAction {
-    /// Specifies that the error should be logged normally and dispatched to the EventHandler.
-    /// Connection retrying will proceed normally if appropriate.
+    /**
+     Specifies that the error should be logged normally and dispatched to the `EventHandler`. Connection retrying will
+     proceed normally if appropriate.
+     */
     case proceed
-    /// Specifies that the connection should be immediately shut down and not retried. The error
-    /// will not be dispatched to the EventHandler
+    /**
+     Specifies that the connection should be immediately shut down and not retried. The error will not be dispatched
+     to the `EventHandler`
+     */
     case shutdown
 }
 
 /// Struct representing received event from the stream.
 public struct MessageEvent: Equatable, Hashable {
-    /// Returns the event data.
+    /// The event data of the event.
     public let data: String
     /// The last seen event id, or the event id set in the Config if none have been received.
     public let lastEventId: String?
 
+    /**
+     Constructor for a `MessageEvent`
+
+     - Parameter data: The `data` field of the `MessageEvent`.
+     - Parameter eventType: The `lastEventId` field of the `MessageEvent`.
+     */
     public init(data: String, lastEventId: String? = nil) {
         self.data = data
         self.lastEventId = lastEventId
@@ -37,24 +51,30 @@ public struct MessageEvent: Equatable, Hashable {
 public protocol EventHandler {
     /// EventSource calls this method when the stream connection has been opened.
     func onOpened()
+
     /// EventSource calls this method when the stream connection has been closed.
     func onClosed()
-    /** EventSource calls this method when it has received a new event from the stream.
+
+    /**
+     EventSource calls this method when it has received a new event from the stream.
 
      - Parameter eventType: The type of the event.
      - Parameter messageEvent: The data for the event.
      */
     func onMessage(eventType: String, messageEvent: MessageEvent)
-    /** EventSource calls this method when it has received a comment line from the stream.
+
+    /**
+     EventSource calls this method when it has received a comment line from the stream.
 
      - Parameter comment: The comment received.
      */
     func onComment(comment: String)
+
     /**
-     This method will be called for all exceptions that occur on the socket connection
-     (including an {@link UnsuccessfulResponseError} if the server returns an unexpected HTTP status),
-     but only after the ConnectionErrorHandler (if any) has processed it.  If you need to
-     do anything that affects the state of the connection, use ConnectionErrorHandler.
+     This method will be called for all exceptions that occur on the network connection (including an
+     `UnsuccessfulResponseError` if the server returns an unexpected HTTP status), but only after the
+     ConnectionErrorHandler (if any) has processed it.  If you need to do anything that affects the state of the
+     connection, use ConnectionErrorHandler.
 
      - Parameter error: The error received.
      */
@@ -63,23 +83,28 @@ public protocol EventHandler {
 
 /// Enum values representing the states of an EventSource
 public enum ReadyState: String, Equatable {
-    /// The EventSource has not been started yet.
+    /// The `EventSource` client has not been started yet.
     case raw
-    /// The EventSource is attempting to make a connection.
+    /// The `EventSource` client is attempting to make a connection.
     case connecting
-    /// The EventSource is active and the EventSource is listening for events.
+    /// The `EventSource` client is active and listening for events.
     case open
-    /// The connection has been closed or has failed, and the EventSource will attempt to reconnect.
+    /// The connection has been closed or has failed, and the `EventSource` will attempt to reconnect.
     case closed
-    /// The connection has been permanently closed and will not reconnect.
+    /// The connection has been permanently closed and the `EventSource` not reconnect.
     case shutdown
 }
 
-/// Error class that means the remote server returned an HTTP error.
+/// Error class that indicates the remote server returned an unsuccessful HTTP response code.
 public class UnsuccessfulResponseError: Error {
-    /// The HTTP response code received
+    /// The HTTP response code received.
     public let responseCode: Int
 
+    /**
+     Constructor for an `UnsuccessfulResponseError`.
+
+     - Parameter responseCode: The HTTP response code of the unsuccessful response.
+     */
     public init(responseCode: Int) {
         self.responseCode = responseCode
     }