Merge remote-tracking branch 'origin/master'

Sources/SwiftChatSE/ChatListener.swift

@@ -38,15 +38,19 @@ open class ChatListener {
 		shutdownHandler = handler
 	}
 
+	///Tells the bot whether to reboot, shutdown or update.
 	public enum StopReason {
-		case halt
-		case reboot
+		case halt   ///Tells the bot to shutdown
+		case reboot ///Tells the bot to reboot
+        ///Tells the bot to update, that is getting the latest code from it's Github repository.
 		case update
 	}
 
 
 	let commandQueue = DispatchQueue(label: "Command Queue", attributes: DispatchQueue.Attributes.concurrent)
-
+
+
+	///The commands the bot is currently running.
 	open var runningCommands = [Command]()
 
 

Sources/SwiftChatSE/ChatRoom.swift

@@ -16,39 +16,62 @@ open class ChatRoom: NSObject {
 
 	///A type of event from the chat room.
 	public enum ChatEvent: Int {
+        ///Caused when a message is posted in the chat room
 		case messagePosted = 1
-		case messageEdited = 2
+        ///Caused when a message is edited in the chat room
+        case messageEdited = 2
+        ///Caused when a user entered the chat room
 		case userEntered = 3
+        ///Caused when a user leaves the chat room
 		case userLeft = 4
+        ///Caused when the name of the room is changed
 		case roomNameChanged = 5
+        ///Caused when a message is stsrred in the chat room
 		case messageStarred = 6
 		case debugMessage = 7
+        ///Caused when a user is mentioned in the chat room
 		case userMentioned = 8
+        ///Caused when a message is flagged in the chat room
 		case messageFlagged = 9
+        ///Caused when a message is deleted in the chat room
 		case messageDeleted = 10
+        ///Caused when a file is uploaded in the chat room
 		case fileAdded = 11
+        ///Caused when a message is mod flagged in the chat room
 		case moderatorFlag = 12
 		case userSettingsChanged = 13
 		case globalNotification = 14
 		case accessLevelChanged = 15
 		case userNotification = 16
+        ///Caused when a user is invited to a chat room
 		case invitation = 17
+        ///Caused when a message is replied to in a chat room
 		case messageReply = 18
+        ///Caused when a Room Owner moves a message to another room
 		case messageMovedOut = 19
+        ///Caused when a Room Owner moves a message to the room
 		case messageMovedIn = 20
+        ///Caused when the room is placed in timeout
 		case timeBreak = 21
 		case feedTicker = 22
+        ///Caused when a user is suspended
 		case userSuspended = 29
+        ///Caused when a user is merged
 		case userMerged = 30
+        ///Caused when a user's username has changed
 		case usernameChanged = 34
 	};
 
-
+	///The host the bot is running on.
 	public enum Host: Int {
+        ///Used when the bot is running on 'stackoverflow.com'
 		case stackOverflow
+        ///Used when the bot is running on 'stackexchange.com'
 		case stackExchange
+        ///Used when the bot is running on 'meta.stackexchange.com'
 		case metaStackExchange
 
+        ///Returns the domain for the specified host
 		public var domain: String {
 			switch self {
 			case .stackOverflow:
@@ -60,14 +83,17 @@ open class ChatRoom: NSObject {
 			}
 		}
 
+        ///Returns the chat domain for the specified host
 		public var chatDomain: String {
 			return "chat." + domain
 		}
 
+        ///Returns the domain URL for the host
 		public var url: URL {
 			return URL(string: "https://" + domain)!
 		}
 
+        ///Returns the URL for the chat host
 		public var chatHostURL: URL {
 			return URL(string: "https://" + chatDomain)!
 		}
@@ -504,12 +530,12 @@ open class ChatRoom: NSObject {
 		}
 	}
 
+    ///The errors which can be caused while the bot joins the room.
 	public enum RoomJoinError: Error {
+        ///When the retrieval of information for a room failed.
 		case roomInfoRetrievalFailed
 	}
 
-
-
 	fileprivate func connectWS() throws {
 		//get the timestamp
 		guard let time = (try client.parseJSON(client.post("https://\(host.chatDomain)/chats/\(roomID)/events", [
@@ -565,10 +591,11 @@ open class ChatRoom: NSObject {
 		try ws.connect()
 	}
 
-
-
+	///An error which happened while the bot was processing a chat event.
 	public enum EventError: Error {
+        ///This is caused when the library cannot parse the specified json.
 		case jsonParsingFailed(json: String)
+        ///This is caused when the chat room event type is invalid.
 		case invalidEventType(type: Int)
 	}
 

Sources/SwiftChatSE/ChatUser.swift

@@ -159,8 +159,7 @@ open class ChatUser: CustomStringConvertible {
 	///The room this user is from.
 	open let room: ChatRoom
 
-
-
+    ///Initializes a chat user
 	public init(room: ChatRoom, id: Int, name: String? = nil) {
 		self.room = room
 		self.id = id

Sources/SwiftChatSE/Client.swift

@@ -55,27 +55,27 @@ open class Client: NSObject, URLSessionDataDelegate {
 			delegate: self, delegateQueue: delegateQueue
 		)
 	}
+    ///Pretty self explanatory
 	open var cookies = [HTTPCookie]()
 	private let queue = DispatchQueue(label: "Client queue")
 
+    ///Indicates whether the client is logged in or not.
 	open var loggedIn = false
 
 	private var configuration: URLSessionConfiguration
 	private var delegateQueue: OperationQueue
 
+    ///Errors which can happen while making a request
 	public enum RequestError: Error {
 		case invalidURL(url: String)
 		case notUTF8
 		case unknownError
 		case timeout
 	}
 
+    ///Indicates the duration of a timeout
 	open var timeoutDuration: TimeInterval = 30
 
-
-
-
-
 	//MARK: - Private variables
 	private class HTTPTask {
 		var task: URLSessionTask
@@ -468,13 +468,13 @@ open class Client: NSObject, URLSessionDataDelegate {
 		]*/
 	}
 
-
-
-
-
+	///Errors which can occur while logging in.
 	public enum LoginError: Error {
+        ///Occurs when the client is already logged in.
 		case alreadyLoggedIn
+        ///Occurs when the data to login is not found.
 		case loginDataNotFound
+        ///Occurs when a login fails.
 		case loginFailed(message: String)
 	}
 

Sources/SwiftChatSE/Command.swift

@@ -14,6 +14,7 @@ open class Command {
         fatalError("usage() must be overriden")
     }
 
+    ///Returns a ChatUser's privileges.
 	open class func privileges() -> ChatUser.Privileges {
 		return []
 	}
@@ -25,6 +26,7 @@ open class Command {
     ///Whether the command has completed execution.  Will be set to true automatically by ChatListener.
     open internal(set) var finished = false
 
+    ///Arguments passed to the command.
     open let arguments: [String]
 
     ///Which usage of the command was run.  Useful for implementing
@@ -37,15 +39,17 @@ open class Command {
 		message.room.postReply(reply, to: message)
 	}
 
+    ///Posts a message.
 	open func post(_ message: String) {
 		self.message.room.postMessage(message)
 	}
 
-
+    ///Runs the command.
     open func run() throws {
         fatalError("run() must be overridden")
     }
 
+    ///Initializes a Command.
     public required init(listener: ChatListener, message: ChatMessage, arguments: [String], usageIndex: Int = 0) {
         self.listener = listener
         self.message = message

Sources/SwiftChatSE/Levenshtein.swift

@@ -41,6 +41,7 @@ public final class Levenshtein {
 		}
 	}
 
+    ///Calclates and returns the levenshtein distance between two strings.
 	public class func distanceBetween(_ aStr: String, and bStr: String) -> Int {
 		let a = Array(aStr.utf16)
 		let b = Array(bStr.utf16)

Sources/SwiftChatSE/WebSocket.swift

@@ -146,6 +146,7 @@ fileprivate func wsLog(level: Int32, buf: UnsafePointer<Int8>?) {
 	}
 }
 
+///Handles all the websocket connections.
 public class WebSocket {
 	public static var debugLoggingEnabled = false
 

docs/CNAME

@@ -0,0 +1 @@
+swiftchatse.sobotics.org