%E5%9B%BA%E5%AE%9A%E7%94%A8%E6%B3%95-%E9%80%9A%E7%94%A8

更新时间不可用



方法调用时机

  • 如果某个方法在注释里面写了需要在加入频道前调用,统一写为:“该方法需要在加入频道前调用。”

回调描述 shortdesc

回调的功能简述请按照下列句式来描述:xxx 回调,例如:

  • 远端视频状态发生改变回调。
  • 远端用户成功加入频道回调。
  • 已接收视频帧回调。

参数描述

  1. 如果一个参数的类型(type)是 bool 类型,则需要以 bullet point 的形式分别解释 true 和 false 所代表的含义,以下为示例:

示例

是否开启加密:

  • true:(默认)开启加密。\n- false:关闭加密。
  • (对于 iOS 和 macOS) YES:(默认)开启加密。\n- NO:关闭加密。
  1. 如果一个参数是输出参数,按照下列示例来描述:

示例

"parameters": [ { "desc": "输出参数,表示 CodecCapInfo 数组的大小。 } ],

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 里面加上代码中枚举值对应的数字,以下为一个示例:

示例

代码: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 字段统一按照下列示例来描述:

示例

  • 该方法自 vx.x.x 版本废弃,请改用 xx。
  • 该回调自 vx.x.x 版本废弃,请改用 xx。
  • 该枚举自 vx.x.x 版本废弃,请改用 xx。
  • 该类自 vx.x.x 版本废弃,请改用 xx。
  • 该参数自 vx.x.x 版本废弃,请改用 xx。

timing 调用时机

  • 如果某个方法在注释里面写了需要在加入频道前调用,统一写为:“该方法需要在加入频道前调用。”

Agora

在描述中,把“agora”、“Agora“ 都统一写为“声网”。API 名称里面的 agora 无需写为”声网“。

since

如果 @ since 有明确具体的版本,按照下列示例来描述:

示例

"since": "自 vx.x.x 版本新增。"

RTM

  • rtm、Rtm 都统一写为 RTM,不加反引号。即使注释中写的是 rtm、Rtm,也处理为 RTM。
  • 在描述中,RTM client、RTM Client 都统一处理为 RTMClient。
  • RTM(全大写)是产品名称,在描述中出现时无需添加 code font。

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<ArrayList<{SubDataType}>>,则后面再加一句,详见 {SubDataType}。
  • 调用失败:执行 onFailure 方法,会返回一个 ErrorInfo。

详见描述

在描述时,统一使用“详见 xxx”,不要使用其他的描述,例如”详情请参考“、”详情参见“等。

声网 App ID

App ID 是声网平台开发中一个重要的概念。请结合上下文,如果上下文中没有出现其他厂商的名字,如 Open AI、火山等,则将 App ID 或者 Agora App ID 替换为“声网 App ID”,并确保大小写与空格和本词条保持一致。App ID 外面不要使用反引号(``)包裹。

Token

声网开发平台中用于验证用户身份的动态密钥。在文本描述中,即除代码和代码块的文档外,无论中文或英文,均处理为 Token,首字母大写,且外面不要使用反引号(``)包裹。

SDK

SDK 是一个经常会被提到的概念。在中英文文本中,请始终使用全大写的格式,并且外面不要使用反引号(``)包裹。

UID

表示用户 ID。如果原文中使用了小写的 uid,需要结合上下文判断是否是表示参数的 uid,还是指用户 ID。如果是参数,则使用 uid 的形式,即反引号 + 全小写;如果表示用户 ID,则使用“用户 ID”。

返回值

如果方法的返回值给了三种或三种以上的情况,则对给出的情况进行一下逻辑整合。

示例

0 if the method call succeeds, -2 if the userId is invalid, other negative values if it fails.

翻译为:

  • 0:方法调用成功
  • < 0:方法调用失败
    • -2: userId 无效

这个页面有帮助吗?