Update API docs

Source/Membership/Membership.swift

@@ -25,14 +25,14 @@ import ObjectMapper
 ///
 /// - since: 2.3.0
 public enum MembershipEvent {
-    // The callback when a user is added to a space.
+    // The event when a user is added to a space.
     case created(Membership)
-    // The callback when a user is removed to a space.
+    // The event when a user is removed from a space.
     case deleted(Membership)
-    // The callback when a membership's properties changed.
+    // The event when a membership's properties changed.
     case update(Membership)
-    /// The callback a membership has sent a read receipt.
-    case seen(Membership, lastSeenMessage: String)
+    /// The event when a membership has sent a read receipt.
+    case messageSeen(Membership, lastSeenMessage: String)
 }
 
 /// Membership contents.
@@ -129,10 +129,10 @@ public struct MembershipReadStatus: ImmutableMappable {
     /// The membership of the space
     public var member: Membership = Membership()
 
-    /// The id of the last message which the member have seen
+    /// The id of the last message which the member have read
     public var lastSeenId: String?
 
-    /// The last date the member have seen
+    /// The last date and time the member have read messages
     public var lastSeenDate: Date?
 
     public init(map: Map) throws {

Source/Membership/MembershipClient.swift

@@ -25,12 +25,12 @@ import Foundation
 /// - since: 1.2.0
 public class MembershipClient {
 
-    /// The callback handler for incoming membership events.
+    /// The callback to receive events about membership changes
     ///
     /// - since: 2.3.0
     public var onEvent: ((MembershipEvent) -> Void)?
 
-    /// The callback handler for incoming membership events with the event payload.
+    /// The callback to receive events with the event payload about membership changes.
     ///
     /// - since: 2.3.0
     public var onEventWithPayload: ((MembershipEvent, WebexEventPayload) -> Void)?
@@ -170,7 +170,7 @@ public class MembershipClient {
     ///
     /// - parameter membershipId: The identifier of the membership.
     /// - parameter queue: If not nil, the queue on which the completion handler is dispatched. Otherwise, the handler is dispatched on the application's main thread.
-    /// - parameter completionHandler: A closure to be executed once the get request has finished.
+    /// - parameter completionHandler: A closure to be executed once the request has finished.
     /// - returns: Void
     /// - since: 1.2.0
     public func get(membershipId: String, queue: DispatchQueue? = nil, completionHandler: @escaping (ServiceResponse<Membership>) -> Void) {
@@ -206,7 +206,7 @@ public class MembershipClient {
     ///
     /// - parameter membershipId: The identifier of the membership.
     /// - parameter queue: If not nil, the queue on which the completion handler is dispatched. Otherwise, the handler is dispatched on the application's main thread.
-    /// - parameter completionHandler: A closure to be executed once the delete request has finished.
+    /// - parameter completionHandler: A closure to be executed once the request has finished.
     /// - returns: Void
     /// - since: 1.2.0
     public func delete(membershipId: String, queue: DispatchQueue? = nil, completionHandler: @escaping (ServiceResponse<Any>) -> Void) {
@@ -219,11 +219,12 @@ public class MembershipClient {
         request.responseJSON(completionHandler)
     }
 
-    /// Return a list of memberships with details about the lastSeenId for each user, allowing a client to indicate "read status" in a space GUI
+    /// Returns a list of memberships with details about the lastSeenId for each user so that application can tell
+    /// which message was the last message was read by each user.
     ///
     /// - parameter spaceId: The identifier of the space.
     /// - parameter queue: If not nil, the queue on which the completion handler is dispatched. Otherwise, the handler is dispatched on the application's main thread.
-    /// - parameter completionHandler: A closure to be executed once the delete request has finished.
+    /// - parameter completionHandler: A closure to be executed once the request has finished.
     /// - returns: Void
     /// - since: 2.3.0
     public func listWithReadStatus(spaceId: String, queue: DispatchQueue? = nil, completionHandler: @escaping (ServiceResponse<[MembershipReadStatus]>) -> Void) {
@@ -275,7 +276,7 @@ extension MembershipClient {
                 membership.personOrgId = activity.actorOrgId
                 membership.personDisplayName = activity.actorDisplayName
                 membership.personEmail = EmailAddress.fromString(activity.actorEmail)
-                event = MembershipEvent.seen(membership, lastSeenMessage: seenId)
+                event = MembershipEvent.messageSeen(membership, lastSeenMessage: seenId)
             }
         }
         else {

Source/Message/Message.swift

@@ -36,7 +36,9 @@ public enum MessageEvent {
 /// - since: 1.2.0
 public struct Message {
 
-    /// This struct for the message text in different formats.
+    /// The wrapper for the message text in different formats: plain text, markdown, and html.
+    /// Please note this version of the SDK requires the application to convert markdown to html.
+    /// Future version of the SDK will provide auto conversion from markdown to html.
     ///
     /// - since: 2.3.0
     public struct Text {
@@ -68,7 +70,7 @@ public struct Message {
         /// Make a Text object for the markdown.
         ///
         /// - parameter markdown: The text with the markdown markup.
-        /// - parameter html: The html text for how to render the markdown.
+        /// - parameter html: The html text for how to render the markdown. This will be optional in the future.
         /// - parameter plain: The alternate plain text for cases that do not support markdown and html markup.
         public static func markdown(markdown: String, html: String, plain: String? = nil) -> Text {
             return Text(plain: plain, html: html, markdown: markdown)
@@ -82,10 +84,10 @@ public struct Message {
     /// The identifier of this message.
     public private(set) var id: String?
 
-    /// Returns the content of the message in different formats.
+    /// Returns the content of the message in as Message.Text object.
     ///
     /// - since: 2.3.0
-    public private(set) var complexText: Message.Text?
+    public private(set) var textAsObject: Message.Text?
 
     /// The identifier of the space where this message was posted.
     public var spaceId: String? {
@@ -142,7 +144,7 @@ public struct Message {
 
     /// The content of the message.
     public var text: String? {
-        return self.complexText?.simple
+        return self.textAsObject?.simple
     }
 
     /// An array of file attachments in the message.
@@ -160,7 +162,7 @@ public struct Message {
         if self.activity.verb == ActivityModel.Verb.delete, let uuid = self.activity.objectUUID {
             self.id = uuid.hydraFormat(for: .message)
         }
-        self.complexText = Message.Text(plain: activity.objectDisplayName, html: activity.objectConetnt, markdown: activity.objectMarkdown)
+        self.textAsObject = Message.Text(plain: activity.objectDisplayName, html: activity.objectConetnt, markdown: activity.objectMarkdown)
     }
 
     private var mentions: [Mention]? {

Source/Message/MessageClient.swift

@@ -455,7 +455,7 @@ public class MessageClient {
     /// - parameter spaceId: The identifier of the space where the message is.
     /// - parameter messageId: The identifier of the message which user read.
     /// - parameter queue: If not nil, the queue on which the completion handler is dispatched. Otherwise, the handler is dispatched on the application's main thread.
-    /// - parameter completionHandler: A closure to be executed once the delete readReceipt has finished.
+    /// - parameter completionHandler: A closure to be executed once the request has finished.
     /// - returns: Void
     /// - since: 2.3.0
     public func markAsRead(spaceId:String, messageId: String, queue: DispatchQueue? = nil, completionHandler: @escaping (ServiceResponse<Any>) -> Void) {
@@ -487,7 +487,7 @@ public class MessageClient {
     ///
     /// - parameter spaceId: The identifier of the space where the message is.
     /// - parameter queue: If not nil, the queue on which the completion handler is dispatched. Otherwise, the handler is dispatched on the application's main thread.
-    /// - parameter completionHandler: A closure to be executed once the delete readReceipt has finished.
+    /// - parameter completionHandler: A closure to be executed once the request has finished.
     /// - returns: Void
     /// - since: 2.3.0
     public func markAsRead(spaceId:String, queue: DispatchQueue? = nil, completionHandler: @escaping (ServiceResponse<Any>) -> Void) {
@@ -1011,7 +1011,7 @@ public class MessageClient {
                      files: [LocalFile]? = nil,
                      queue: DispatchQueue? = nil,
                      completionHandler: @escaping (ServiceResponse<Message>) -> Void) {
-        self.post(text?.toComplexText, toPersonEmail: personEmail, withFiles: files, queue: queue, completionHandler: completionHandler)
+        self.post(text?.toTextObject, toPersonEmail: personEmail, withFiles: files, queue: queue, completionHandler: completionHandler)
     }
 
     /// Posts a message with optional file attachments to a user by id.
@@ -1031,7 +1031,7 @@ public class MessageClient {
                      files: [LocalFile]? = nil,
                      queue: DispatchQueue? = nil,
                      completionHandler: @escaping (ServiceResponse<Message>) -> Void) {
-        self.post(text?.toComplexText, toPerson: personId, withFiles: files, queue: queue, completionHandler: completionHandler)
+        self.post(text?.toTextObject, toPerson: personId, withFiles: files, queue: queue, completionHandler: completionHandler)
     }
 
     /// Posts a message with optional file attachments to a space by spaceId.
@@ -1056,7 +1056,7 @@ public class MessageClient {
                      files: [LocalFile]? = nil,
                      queue: DispatchQueue? = nil,
                      completionHandler: @escaping (ServiceResponse<Message>) -> Void) {
-        self.post(text?.toComplexText, toSpace: spaceId, mentions: mentions, withFiles: files, queue: queue, completionHandler: completionHandler)
+        self.post(text?.toTextObject, toSpace: spaceId, mentions: mentions, withFiles: files, queue: queue, completionHandler: completionHandler)
     }
 }
 
@@ -1073,7 +1073,7 @@ extension Date {
 
 extension String {
 
-    var toComplexText: Message.Text {
+    var toTextObject: Message.Text {
         return Message.Text.html(html: self, plain: self)
     }
 

Source/Space/Space.swift

@@ -136,7 +136,7 @@ public struct SpaceReadStatus: ImmutableMappable {
     /// The date of last activity in the space.
     public var lastActivityDate: Date?
 
-    /// The date of the last message in the space that login user seen.
+    /// The date of the last message in the space that login user has read.
     public var lastSeenActivityDate: Date?
 
     private let dateTransform = CustomDateFormatTransform(formatString: "yyyy-MM-dd'T'HH:mm:ss.SSSZZZZZ")

Source/TeamMembership/TeamMembershipClient.swift

@@ -109,7 +109,7 @@ public class TeamMembershipClient {
     ///
     /// - parameter membershipId: The identifier of the membership.
     /// - parameter queue: The queue on which the completion handler is dispatched.
-    /// - parameter completionHandler: A closure to be executed once the get request has finished.
+    /// - parameter completionHandler: A closure to be executed once the request has finished.
     /// - returns: Void
     /// - since: 1.2.0
    public func get(membershipId: String, queue: DispatchQueue? = nil, completionHandler: @escaping (ServiceResponse<TeamMembership>) -> Void) {
@@ -145,7 +145,7 @@ public class TeamMembershipClient {
     ///
     /// - parameter membershipId: The identifier of the membership.
     /// - parameter queue: The queue on which the completion handler is dispatched.
-    /// - parameter completionHandler: A closure to be executed once the delete request has finished.
+    /// - parameter completionHandler: A closure to be executed once the request has finished.
     /// - returns: Void
     /// - since: 1.2.0
     public func delete(membershipId: String, queue: DispatchQueue? = nil, completionHandler: @escaping (ServiceResponse<Any>) -> Void) {

Source/WebexEvent.swift

@@ -21,7 +21,7 @@
 
 import Foundation
 
-/// The raw payload of the event.
+/// The payload of the event.
 ///
 /// - since: 2.3.0
 public struct WebexEventPayload {
@@ -32,7 +32,7 @@ public struct WebexEventPayload {
         //        self.orgId = person?.orgId
     }
 
-    /// Returns the personId of the user that caused the event to be sent. For example, for a messsage received event,
+    /// Returns the identifier of the user that caused the event to be sent. For example, for a messsage received event,
     /// the author of the message will be the actor. For a membership deleted event, the actor is the person who removed the user
     /// from space.
     public let actorId: String?