From a9272e986c6407f75610570e4bfe3805d13e0061 Mon Sep 17 00:00:00 2001 From: kliu Date: Sun, 29 Sep 2019 20:19:35 +0800 Subject: [PATCH] Update API docs --- Source/Membership/Membership.swift | 14 +++++++------- Source/Membership/MembershipClient.swift | 15 ++++++++------- Source/Message/Message.swift | 14 ++++++++------ Source/Message/MessageClient.swift | 12 ++++++------ Source/Space/Space.swift | 2 +- Source/TeamMembership/TeamMembershipClient.swift | 4 ++-- Source/WebexEvent.swift | 4 ++-- 7 files changed, 34 insertions(+), 31 deletions(-) diff --git a/Source/Membership/Membership.swift b/Source/Membership/Membership.swift index 8bbe8de5..06602411 100755 --- a/Source/Membership/Membership.swift +++ b/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 { diff --git a/Source/Membership/MembershipClient.swift b/Source/Membership/MembershipClient.swift index 6ddc3b7b..a103c14f 100755 --- a/Source/Membership/MembershipClient.swift +++ b/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) -> 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) -> 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 { diff --git a/Source/Message/Message.swift b/Source/Message/Message.swift index c97cf78b..3873a578 100644 --- a/Source/Message/Message.swift +++ b/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]? { diff --git a/Source/Message/MessageClient.swift b/Source/Message/MessageClient.swift index 89d2f4f8..259c09be 100644 --- a/Source/Message/MessageClient.swift +++ b/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) -> 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) -> Void) { @@ -1011,7 +1011,7 @@ public class MessageClient { files: [LocalFile]? = nil, queue: DispatchQueue? = nil, completionHandler: @escaping (ServiceResponse) -> 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) -> 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) -> 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) } diff --git a/Source/Space/Space.swift b/Source/Space/Space.swift index b795dfdf..e7977629 100755 --- a/Source/Space/Space.swift +++ b/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") diff --git a/Source/TeamMembership/TeamMembershipClient.swift b/Source/TeamMembership/TeamMembershipClient.swift index 37fed4e2..b97fca7a 100755 --- a/Source/TeamMembership/TeamMembershipClient.swift +++ b/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) -> 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) -> Void) { diff --git a/Source/WebexEvent.swift b/Source/WebexEvent.swift index 506230a2..e963adfe 100644 --- a/Source/WebexEvent.swift +++ b/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?