# undefined (/zh-CN/introduction/terms/%E4%B8%AD%E6%96%87%E7%BF%BB%E8%AF%91/%E5%9B%BA%E5%AE%9A%E7%94%A8%E6%B3%95/%E5%9B%BA%E5%AE%9A%E7%94%A8%E6%B3%95-%E9%80%9A%E7%94%A8) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). --- --- ## 方法调用时机 [#方法调用时机] - 如果某个方法在注释里面写了需要在加入频道前调用,统一写为:“该方法需要在加入频道前调用。” ## 回调描述 shortdesc [#回调描述-shortdesc] 回调的功能简述请按照下列句式来描述:xxx 回调,例如: - 远端视频状态发生改变回调。 - 远端用户成功加入频道回调。 - 已接收视频帧回调。 ## 参数描述 [#参数描述] 1. 如果一个参数的类型(type)是 bool 类型,则需要以 bullet point 的形式分别解释 true 和 false 所代表的含义,以下为示例: ### 示例 [#示例] 是否开启加密: - `true`:(默认)开启加密。\n- `false`:关闭加密。 - (对于 iOS 和 macOS) `YES`:(默认)开启加密。\n- `NO`:关闭加密。 2. 如果一个参数是输出参数,按照下列示例来描述: ### 示例 [#示例-1] "parameters": [ { "desc": "输出参数,表示 `CodecCapInfo` 数组的大小。 } ], ## javascript 参数描述 [#javascript-参数描述] - 在描述参数时,请结合 api_signature 的 API 原型来判断,如果参数的类型是一个类型、枚举类型或 interface,按照以下示例来描述: ###示例 - 示例 1: network-quality(stats: NetworkQuality): void "parameters": [ { "name": "stats", "type": "NetworkQuality", "desc": "网络质量,详见 `NetworkQuality`。其他信息(如有)" } ], - 示例 2: stream-type-changed(streamType: RemoteStreamType): void "parameters": [ { "name": "streamType", "type": "RemoteStreamType", "desc": "视频流类型,详见 `RemoteStreamType`。\n- 0:视频大流。\n- 1:视频小流。" } ], - 示例 3: published-user-list(users: IAgoraRTCRemoteUser[]): void "parameters": [ { "name": "users", "type": "IAgoraRTCRemoteUser", "desc": "远端用户对象,详见 `IAgoraRTCRemoteUser`。其他信息(如有)" } ], ### ## 枚举值描述 [#枚举值描述] - 同一个 enum 里面的枚举值描述,使用同样的句型来描述。 - 在描述枚举值时,需要在 desc 里面加上代码中枚举值对应的数字,以下为一个示例: ### 示例 [#示例-2] 代码:enum AudioRoute { ROUTE_DEFAULT = -1, }; "desc":"(-1):默认路由。" ## 描述术语统一 [#描述术语统一] - “agora” 写为 “声网” - error code 写为 “错误码” - remote user id/remote uid/id of remote user 都写为 “远端用户 ID“ - channel name 写为 “频道名” - custom audio source 写为 “自定义音频源” - custom video source 写为 “自定义视频源” ## 取值范围 [#取值范围] - API 参数取值范围:a,b、[a,b)。 - 其他区间范围:a ≤ X ≤ b,a ≤ X < b。 - 表示英文字母: a~z。 - 中文:9 亿到 12 亿。 ## 单位统一 [#单位统一] - 千赫兹统一写为 kHz - 千比特率统一写为 Kbps ## 废弃信息 [#废弃信息] 如果某个 API、struct、enum 自某个版本废弃,deprecated 字段统一按照下列示例来描述: ### 示例 [#示例-3] - 该方法自 vx.x.x 版本废弃,请改用 xx。 - 该回调自 vx.x.x 版本废弃,请改用 xx。 - 该枚举自 vx.x.x 版本废弃,请改用 xx。 - 该类自 vx.x.x 版本废弃,请改用 xx。 - 该参数自 vx.x.x 版本废弃,请改用 xx。 ## timing 调用时机 [#timing-调用时机] - 如果某个方法在注释里面写了需要在加入频道前调用,统一写为:“该方法需要在加入频道前调用。” ## Agora [#agora] 在描述中,把“agora”、“Agora“ 都统一写为“声网”。API 名称里面的 agora 无需写为”声网“。 ## since [#since] 如果 @ since 有明确具体的版本,按照下列示例来描述: ### 示例 [#示例-4] "since": "自 vx.x.x 版本新增。" ## RTM [#rtm] - rtm、Rtm 都统一写为 RTM,不加反引号。即使注释中写的是 rtm、Rtm,也处理为 RTM。 - 在描述中,RTM client、RTM Client 都统一处理为 `RTMClient`。 - RTM(全大写)是产品名称,在描述中出现时无需添加 code font。 ## Java ResultCallback [#java-resultcallback] 在处理 Java 语言时,如果参数为 resultCallback,并且参数类型是 ResultCallback<> 格式,则结合注释内容,将 \* @param resultCallback A {@link ResultCallback} object. - - Success: will receives the - {@link ResultCallback#onSuccess(Object)} callback. - - Failure: will receives the - {@link ResultCallback#onFailure(ErrorInfo)} callback.翻译为: 如果数据类型是 ResultCallback,则翻译为: 一个 `ResultCallback` 对象: - 调用成功:执行 `onSuccess` 方法。 - 调用失败:执行 `onFailure` 方法,会返回一个 `ErrorInfo`。 如果数据类型是 ResultCallback<{dataType}>,则翻译为: 一个 `ResultCallback` 对象: - 调用成功:执行 `onSuccess` 方法,并返回 `{dataType}` 的查询结果。如果 {dataType} 中是一个 ArrayList,如 ResultCallabck