%E5%9B%BA%E5%AE%9A%E7%94%A8%E6%B3%95-%E9%80%9A%E7%94%A8
更新时间不可用
方法调用时机
- 如果某个方法在注释里面写了需要在加入频道前调用,统一写为:“该方法需要在加入频道前调用。”
回调描述 shortdesc
回调的功能简述请按照下列句式来描述:xxx 回调,例如:
- 远端视频状态发生改变回调。
- 远端用户成功加入频道回调。
- 已接收视频帧回调。
参数描述
- 如果一个参数的类型(type)是 bool 类型,则需要以 bullet point 的形式分别解释 true 和 false 所代表的含义,以下为示例:
示例
是否开启加密:
true:(默认)开启加密。\n-false:关闭加密。- (对于 iOS 和 macOS)
YES:(默认)开启加密。\n-NO:关闭加密。
- 如果一个参数是输出参数,按照下列示例来描述:
示例
"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无效
- -2: