finish doc

Martin91 · Oct 9, 2016 · fb351cc · fb351cc
1 parent 9f3a142
commit fb351cc
Show file tree

Hide file tree

Showing 8 changed files with 97 additions and 4 deletions.
diff --git a/lib/rong_cloud.rb b/lib/rong_cloud.rb
@@ -2,6 +2,7 @@
 require 'rong_cloud/errors'
 require 'rong_cloud/service'
 
+# 融云 Ruby SDK 的全局命名空间
 module RongCloud
   # 配置融云 Server 连接信息
   #

diff --git a/lib/rong_cloud/configuration.rb b/lib/rong_cloud/configuration.rb
@@ -1,16 +1,22 @@
 require "logger"
 
 module RongCloud
+  # 管理融云 SDK 连接配置信息
+  #
   module Configuration
+    # 默认 API 服务器，使用 https
     DEFAULT_HOST = "https://api.cn.ronghub.com".freeze
 
     module ModuleMethods
       attr_accessor :app_key, :app_secret, :host, :logger
 
+      # 获取目标主机，默认为 https://api.cn.ronghub.com
+      #
       def host
         @host || DEFAULT_HOST
       end
 
+      # 获取日志文件对象，默认日志文件为标准输出
       def logger
         @logger || default_logger
       end

diff --git a/lib/rong_cloud/errors.rb b/lib/rong_cloud/errors.rb
@@ -1,18 +1,31 @@
 module RongCloud
+  # 不支持的消息类型错误
   class UnsupportedMessageChannelName < ::StandardError;end
+  # 与融云接口请求相关的基本错误类型，其他错误类型继承此类型
   class RequestError < ::StandardError
+    # @!attribute [rw] business_code
+    #   接口错误时的业务返回码，详见：http://www.rongcloud.cn/docs/server.html#API_方法返回值说明
     attr_accessor :business_code
   end
 
+  # 错误请求
   class BadRequest < RequestError;end
+  # 验证错误
   class AuthenticationFailed < RequestError;end
+  # 被拒绝
   class RequestForbidden < RequestError;end
+  # 资源不存在
   class ResourceNotFound < RequestError;end
+  # 群上限
   class ExceedLimit < RequestError;end
+  # 过多的请求
   class TooManyRequests < RequestError;end
+  # 内部服务器错误
   class InternalServerError < RequestError;end
+  # 内部服务器响应超时
   class Timeout < RequestError;end
 
+  # 融云服务器响应状态码到 Ruby 错误类型的映射
   HTTP_CODE_TO_ERRORS_MAP = {
     "400" => BadRequest,
     "401" => AuthenticationFailed,

diff --git a/lib/rong_cloud/services/group.rb b/lib/rong_cloud/services/group.rb
@@ -1,6 +1,9 @@
 module RongCloud
   module Services
+    # 群组服务相关接口 http://www.rongcloud.cn/docs/server.html#群组服务
     module Group
+      # 同步用户所属群组
+      #
       # @param user_id [String] 用户在融云的 id
       # @param groups [Hash] 用户需要同步的群组信息，以群组 id 为键，以群组名称为值
       #
@@ -13,38 +16,55 @@ def sync_group(user_id, groups)
         request("/group/sync", params)
       end
 
+      # 创建群组
+      #
       def create_group(user_id, group_id, group_name)
         request("/group/create", userId: user_id, groupId: group_id, groupName: group_name)
       end
 
+      # 加入群组
+      #
       def join_group(user_id, group_id, group_name)
         request("/group/join", userId: user_id, groupId: group_id, groupName: group_name)
       end
 
+      # 退出群组
+      #
       def quit_group(user_id, group_id)
         request("/group/quit", userId: user_id, groupId: group_id)
       end
 
+      # 解散群组
+      #
       def dismiss_group(user_id, group_id)
         request("/group/dismiss", userId: user_id, groupId: group_id)
       end
 
+      # 刷新群组信息
       def refresh_group(group_id, group_name)
         request("/group/refresh", groupId: group_id, groupName: group_name)
       end
 
+      # 查询群成员
+      #
       def group_members(group_id)
         request("/group/user/query", groupId: group_id)
       end
 
+      # 添加禁言群成员
+      #
       def block_group_member(user_id, group_id, minute)
         request("/group/user/gag/add", userId: user_id, groupId: group_id, minute: minute)
       end
 
+      # 移除禁言群成员
+      #
       def unblock_group_member(user_id, group_id)
         request("/group/user/gag/rollback", userId: user_id, groupId: group_id)
       end
 
+      # 查询被禁言群成员
+      #
       def blocked_group_members(group_id)
         request("/group/user/gag/list", groupId: group_id)
       end

diff --git a/lib/rong_cloud/services/message.rb b/lib/rong_cloud/services/message.rb
@@ -2,6 +2,7 @@
 
 module RongCloud
   module Services
+    # 消息发送相关接口 http://www.rongcloud.cn/docs/server.html#消息发送服务
     module Message
       # 通用的发送消息方法
       # @param from_user_id [String] 消息发起人 id
@@ -27,22 +28,28 @@ def send_message(from_user_id, target_id, channel_name, object_name, content, op
         request(message_channel.api_path, params)
       end
 
+      # 发送单聊消息 http://www.rongcloud.cn/docs/server.html#发送单聊消息_方法
+      #
       def send_private_message(from_user_id, to_user_id, object_name, content, options = {})
         send_message(from_user_id, to_user_id, :private, object_name, content, options)
       end
 
+      # 发送系统消息 http://www.rongcloud.cn/docs/server.html#发送系统消息_方法
       def send_system_message(from_user_id, to_user_id, object_name, content, options = {})
         send_message(from_user_id, to_user_id, :system, object_name, content, options)
       end
 
+      # 发送群组消息 http://www.rongcloud.cn/docs/server.html#发送群组消息_方法
       def send_group_message(from_user_id, to_group_id, object_name, content, options = {})
         send_message(from_user_id, to_group_id, :group, object_name, content, options)
       end
 
+      # 发送讨论组消息 http://www.rongcloud.cn/docs/server.html#发送讨论组消息_方法
       def send_discussion_message(from_user_id, to_discussion_id, object_name, content, options = {})
         send_message(from_user_id, to_discussion_id, :discussion, object_name, content, options)
       end
 
+      # 发送广播消息 http://www.rongcloud.cn/docs/server.html#发送广播消息_方法
       def send_broadcast_message(from_user_id, object_name, content, options = {})
         send_message(from_user_id, nil, :broadcast, object_name, content, options)
       end

diff --git a/lib/rong_cloud/services/message/message_channel.rb b/lib/rong_cloud/services/message/message_channel.rb
@@ -1,7 +1,10 @@
 module RongCloud
   module Services
     module Message
+      # 消息发送渠道，区分私信、系统消息、群组消息、讨论组消息、聊天室消息以及广播消息
       class MessageChannel
+        # 各消息渠道各自对应请求路径以及特殊参数名
+        #
         CHANNEL_TO_REQUEST_DETAILS_MAP = {
           'private': { target_param_name: "toUserId", api_path: "/message/private/publish" },
           system: { target_param_name: "toUserId", api_path: "/message/system/publish" },
@@ -10,8 +13,16 @@ class MessageChannel
           chatroom: { target_param_name: "toChatroomId", api_path: "/message/chatroom/publish" },
           broadcast: { api_path: "/message/broadcast" }
         }.freeze
+        # 支持的消息渠道的列表
+        #
         VALID_CHANNEL_NAMES = CHANNEL_TO_REQUEST_DETAILS_MAP.keys.map(&:to_s).freeze
 
+        # 实例化消息渠道对象
+        #
+        # @param channel_name [String] 渠道名称
+        # @return [RongCloud::Services::Message::MessageChannel] 消息渠道实例
+        # @raise [RongCloud::UnsupportedMessageChannelName] 消息渠道不支持
+        #
         def initialize(channel_name)
           if VALID_CHANNEL_NAMES.include?(channel_name.to_s)
             @channel_name = channel_name.to_s.to_sym

diff --git a/lib/rong_cloud/services/user.rb b/lib/rong_cloud/services/user.rb
@@ -1,41 +1,67 @@
 module RongCloud
   module Services
+    # 用户相关接口 http://www.rongcloud.cn/docs/server.html#用户服务
     module User
-      def get_token(user_id, name, portraitUri)
-        request("/user/getToken", {userId: user_id, name: name, portraitUri: portraitUri})
+      # 获取 Token，即创建融云用户
+      #
+      # @param user_id [String] 用户 Id，最大长度 64 字节。是用户在 App 中的唯一标识码，必须保证在同一个 App 内不重复，重复的用户 Id 将被当作是同一用户
+      # @param name [String] 用户名称，最大长度 128 字节。用来在 Push 推送时显示用户的名称。
+      # @param portrait_uri [String] 用户头像 URI，最大长度 1024 字节。用来在 Push 推送时显示用户的头像。
+      # @return [Hash] 请求响应结果数据
+      #
+      def get_token(user_id, name, portrait_uri)
+        request("/user/getToken", {userId: user_id, name: name, portraitUri: portrait_uri})
       end
 
-      def refresh_user(user_id, name = nil, portraitUri = nil)
-        params = { userId: user_id, name: name, portraitUri: portraitUri }
+      # 刷新用户信息
+      #
+      def refresh_user(user_id, name = nil, portrait_uri = nil)
+        params = { userId: user_id, name: name, portraitUri: portrait_uri }
         params.reject!{|key, value| value.nil?}
 
         request("/user/refresh", params)
       end
 
+      # 检查用户在线状态
+      #
       def check_online(user_id)
         request("/user/checkOnline", { userId: user_id })
       end
 
+      # 封禁用户
+      # @param user_id [String] 用户在融云的用户 id
+      # @param minute [Integer] 封禁时长
+      #
       def block_user(user_id, minute)
         request("/user/block", { userId: user_id, minute: minute })
       end
 
+      # 解除用户封禁
+      #
       def unblock_user(user_id)
         request("/user/unblock", userId: user_id)
       end
 
+      # 查询被封禁用户列表
+      #
       def blocked_users
         request("/user/block/query")
       end
 
+      # 添加用户到黑名单
+      #
       def blacklist_add(user_id, black_user_id)
         request("/user/blacklist/add", userId: user_id, blackUserId: black_user_id)
       end
 
+      # 从黑名单中移除用户
+      #
       def blacklist_remove(user_id, black_user_id)
         request("/user/blacklist/remove", userId: user_id, blackUserId: black_user_id)
       end
 
+      # 获取某用户的黑名单列表
+      #
       def blacklisted_users(user_id)
         request("/user/blacklist/query", userId: user_id)
       end

diff --git a/lib/rong_cloud/services/wordfilter.rb b/lib/rong_cloud/services/wordfilter.rb
@@ -1,14 +1,23 @@
 module RongCloud
   module Services
+    # 敏感词相关接口 http://www.rongcloud.cn/docs/server.html#敏感词服务
     module Wordfilter
+      # 添加敏感词
+      #
+      # @param word [String] 敏感词
+      #
       def add_wordfilter(word)
         request("/wordfilter/add", { word: word })
       end
 
+      # 移除敏感词
+      #
       def delete_wordfilter(word)
         request("/wordfilter/delete", { word: word })
       end
 
+      # 查询已有敏感词的列表
+      #
       def wordfilter_list
         request("/wordfilter/list")
       end