Reviewed Displayer.java, Player.java and other related files

Android--CN/sdk/AudioMixerBridge.java

@@ -12,7 +12,7 @@
  * 为解决上述问题，你可以使用 `AudioMixerBridge` 接口，以调用 RTC SDK 的混音方法播放动态 PPT 中的音频文件。
  *
  * @note
- * 仅当用户使用的 RTC SDK 支持混音方法时，该方法才会生效。
+ * 仅当用户使用的 RTC SDK 支持混音方法时，该接口的方法才会生效。//TODO WJ 这个支持是指 SDK 版本要求吗？RTC SDK 很早就支持混音了吧
  */
 public interface AudioMixerBridge {
     /**
@@ -24,10 +24,10 @@ public interface AudioMixerBridge {
      * - `true`：只有本地可以听到混音的音频流。
      * - `false`：本地和对方都可以听到混音的音频流。
      * @param replace 是否播放麦克风采集的音频：
-     * - `true`： 只播音频文件，不播麦克风采集的音频。
-     * - `false`: 将音频文件和麦克风采集的音频混音。
+     * - `true`： 只播放音频文件，不播放麦克风采集的音频。
+     * - `false`: 将音频文件和麦克风采集的音频混音后播放。
      * @param cycle 音频文件循环播放的次数：
-     * - 正整数：循环的次数。
+     * - 正整数：循环的次数。//TODO WJ 这里的描述要跟着 RTC 修改，主要是 0 的问题。
      * - -1：无限循环。
     void startAudioMixing(String filepath, boolean loopback, boolean replace, int cycle);
 

Android--CN/sdk/AudioMixerImplement.java

@@ -22,7 +22,7 @@ public class AudioMixerImplement {
      * PPT 根据收到的音频播放状态判断是否显示画面，以确保音画同步。
      *
      * @note
-     * 如果 RTC SDK 没有混音状态回调方法，会导致播放的 PPT音画不同步。
+     * 如果 RTC SDK 没有混音状态回调方法，会导致播放的 PPT 音画不同步。//TODO WJ 什么叫 SDK 没有混音状态回调方法？
      *
      * @param state 音乐文件播放状态：
      *  - MEDIA_ENGINE_AUDIO_EVENT_MIXING_PLAY(710): RTC SDK 成功调用 `startAudioMixing` 播放音乐文件或 `resumeAudioMixing`  恢复播放音乐文件。

Android--CN/sdk/CommonCallbacks.java

@@ -15,7 +15,7 @@ public interface CommonCallbacks {
 
     /**
      *  SDK 出现未捕获的全局错误回调。
-     * @param args
+     * @param args //TODO WJ 缺注释
      */
     void throwError(Object args);
 
@@ -30,7 +30,7 @@ public interface CommonCallbacks {
      * @note
      * 由于该回调过于频繁，Agora 不推荐使用；在 Android 平台，可以使用 WebView 的拦截功能进行图片拦截。
      *
-     * @param sourceUrl 图片原地址。
+     * @param sourceUrl 图片源地址。
      * @return 替换后的图片地址。
      */
     String urlInterrupter(String sourceUrl);
@@ -53,7 +53,7 @@ public interface CommonCallbacks {
      *
      * @since 2.11.4
      *
-     * 当本地用户收到了网页，如 iframe 插件，动态 PPT 发送的消息时会触发该回调。
+     * 当本地用户收到了网页（如 iframe 插件、动态 PPT）发送的消息时会触发该回调。
      *
      * @note
      * 不保证所有用户都能接收到该回调。
@@ -67,8 +67,8 @@ public interface CommonCallbacks {
      *
      * @since 2.9.14
      *
-     * 如果 SDK 初始化失败，调用加入实时房间或回放房间时会处于一直无响应状态，需要重新初始化 SDK。
-     * - 初始化 SDK 时候，网络异常，导致获取配置信息失败。
+     * 如果 SDK 初始化失败，调用加入实时房间或回放房间的方法时会处于一直无响应状态，需要重新初始化 SDK。
+     * - 初始化 SDK 时候，网络异常，导致获取配置信息失败。//TODO WJ 这里是列了两个可能的失败原因？需要在前面加一些文字连起来。
      * - 传入了不合法的 App Identifier。
      * @since 2.9.14
      */

Android--CN/sdk/Displayer.java

@@ -48,11 +48,11 @@ public class Displayer {
     protected ConcurrentHashMap<String, FrequencyEventListener> frequencyEventListenerConcurrentHashMap = new ConcurrentHashMap<>();
 
     /**
-     * Displayer 类的构造函数。
-     * @param uuid 用户 ID。
+     * Displayer 类的构造函数。 //TODO WJ SDK 内部调用的，可以不暴露在文档里
+     * @param uuid 白板房间的 UUID。
      * @param bridge 白板界面，详见 {@link WhiteboardView}。
      * @param context Android 的 Context。
-     * @param sdk White SDK 的初始化设置，详见 {@link WhiteSdk}。
+     * @param sdk 白板 SDK 的初始化设置，详见 {@link WhiteSdk}。
      */
     public Displayer(String uuid, WhiteboardView bridge, Context context, WhiteSdk sdk) {
         this.uuid = uuid;
@@ -73,10 +73,10 @@ public void postIframeMessage(String string) {
     /**
      * 向 iframe 插件发送 key-value 格式的信息。
      *
-     * 你可以通过创建 WhiteObject 的子类来创建一个 ley-value 格式的信息。
+     * 你可以通过创建 WhiteObject 的子类来创建一个 key-value 格式的信息。
      *
      * @param object `Whiteobject` 的子类，详见 {@link WhiteObject}。
-     * @since 2.11.4
+     * @since 2.11.4 //TODO WJ 版本信息的 tag 位置要放到描述开头。
      */
     public void postIframeMessage(WhiteObject object) {
         bridge.callHandler("displayer.postMessage", new Object[]{object});
@@ -85,9 +85,9 @@ public void postIframeMessage(WhiteObject object) {
     /**
      * 查询场景路径类型。
      *
-     * 你可以在该方法中指定想要查询的场景路径，SDK 会返回该路径对应的场景类型，是场景，还是场景目录，或者不存在任何内容。
-     * @param path 想要查询的场景类型。
-     * @param promise `Promise<WhiteScenePathType>` 接口实例，详见 {@link WhiteScenePathTType}。你可以通过该接口获取查询场景路径类型的结果：
+     * 你可以在该方法中指定想要查询的场景路径，SDK 会返回该路径对应的场景类型。
+     * @param path 想要查询的场景路径。
+     * @param promise `Promise<WhiteScenePathType>` 接口实例，详见 {@link WhiteScenePathType}。你可以通过该接口获取查询场景路径类型的结果：
      * - 如果查询成功，将返回场景路径类型。
      * - 如果查询失败，将返回错误信息。
      */
@@ -130,7 +130,7 @@ public void refreshViewSize() {
     }
 
     /**
-     * 以连续动画的形式等比例缩放 PPT。
+     * 以连续动画的形式等比例缩放视角，以保证完整显示 PPT 的内容。//TODO WJ 这里的连续动画是指渐变模式吗？如果是的话，建议统一用词
      *
      * 该方法用于确保 PPT 页面的所有内容都在视野范围内。
      * @since 2.4.22
@@ -140,11 +140,11 @@ public void scalePptToFit() {
     }
 
     /**
-     * 等比例缩放 PPT。
+     * 等比例缩放视角，以保证完整显示 PPT 的内容。
      *
      * 该方法用于确保 PPT 页面的内容都在视野内。
      *
-     * @param mode PPT 缩放时的动画行为，详见 {@link AnimationMode}。
+     * @param mode PPT 缩放时的动画模式，详见 {@link AnimationMode}。
      * @since 2.4.28
      */
     public void scalePptToFit(AnimationMode mode) {
@@ -158,7 +158,7 @@ public void scalePptToFit(AnimationMode mode) {
      * @note 对于同名的自定义事件，SDK 仅支持触发一个回调。
      *
      * @param eventName 想要监听的自定义事件名称。
-     * @param eventListener 自定义事件回调，详见 {@link EventListener}。如果添加多个事件回调，则之前添加的回调会被覆盖。
+     * @param eventListener 自定义事件回调，详见 {@link EventListener}。如果添加多个事件回调，则之前添加的回调会被覆盖。//TODO WJ 这里说的添加多个事件回调是指多个同名的事件回调吗？
      */
     public void addMagixEventListener(String eventName, EventListener eventListener) {
         this.eventListenerConcurrentHashMap.put(eventName, eventListener);
@@ -171,8 +171,8 @@ public void addMagixEventListener(String eventName, EventListener eventListener)
      * @note 对于同名的自定义事件，SDK 仅支持触发一个回调。
      *
      * @param eventName 想要监听的自定义事件名称。
-     * @param eventListener 自定义事件回调，详见 {@link FrequencyEventListener}。如果添加多个事件回调，则之前添加的回调会被覆盖。
-     * @param fireInterval SDK 触发回调的频率，单位为毫秒。该参数最小值为 500ms；低于该值会被传入重置为 500ms。
+     * @param eventListener 自定义事件回调，详见 {@link FrequencyEventListener}。如果添加多个事件回调，则之前添加的回调会被覆盖。//TODO WJ 这里说的添加多个事件回调是指多个同名的事件回调吗？
+     * @param fireInterval SDK 触发回调的频率，单位为毫秒。该参数最小值为 500 ms，如果设置为低于该值会被重置为 500 ms。
      */
     public void addHighFrequencyEventListener(String eventName, FrequencyEventListener eventListener, Integer fireInterval) {
         if (fireInterval < 500) {
@@ -267,7 +267,7 @@ private static Float[] hexSplit(@ColorInt int color) {
      *
      * @since 2.4.0
      *
-     * @return 本地白板的背景色。，格式为 16 进制 ARGB 定义下的 Hex 值。
+     * @return 本地白板的背景色，格式为 16 进制 ARGB 定义下的 Hex 值。
      */
     public int getBackgroundColor() {
         return backgroundColor;
@@ -281,7 +281,7 @@ public int getBackgroundColor() {
      * @param scenePath 指定的场景路径。
      * @param promise `Promise<Bitmap>` 接口实例，详见 {@link Promise}。你可以通过该接口了解获取场景预览图的结果：
      * - 如果获取成功，将返回获取的预览图。
-     * - 如果获取失败，将反馈错误码。
+     * - 如果获取失败，将返回错误码。
      * @since 2.3.0
      */
     public void getScenePreviewImage(String scenePath, final Promise<Bitmap>promise) {
@@ -304,7 +304,7 @@ public void onValue(String retValue) {
     /**
      * 获取特定场景的截图。
      *
-     * 该方法可用于实现用户切换到对应场景时，能立刻看到该场景内容的功能。
+     * 该方法可用于实现用户切换到对应场景时，能立刻看到该场景内容的功能。//TODO WJ 这句话是不是应该删掉，怎么和预览的功能一模一样
      *
      * @param scenePath 指定的场景路径。
      * @param promise `Promise<Bitmap>` 接口实例，详见 {@link Promise}。你可以通过该接口了解获取场景截图的结果：
@@ -338,33 +338,33 @@ private Bitmap transformBase64toBitmap(String base64String) {
     }
 
     /**
-     * 禁止/允许用户移动视角。
+     * 禁止/允许用户缩放白板视野。
      *
-     * 移动视角是指用户可以通过触屏手势放大或缩小白板视野。
+     * 该方法可以设置是否允许用户通过触屏手势放大或缩小白板视野。
      *
-     * @param disable 是否禁止用户移动视角：
-     * - true: 禁止用户移动视角。
-     * - false: (默认) 允许用户移动视角。
+     * @param disable 是否禁止用户缩放白板视野：
+     * - true: 禁止用户缩放白板视野。
+     * - false: (默认) 允许用户缩放白板视野。
      * @since 2.11.0
      */
     public void disableCameraTransform(Boolean disable) {
         bridge.callHandler("displayer.setDisableCameraTransform", new Object[]{disable});
     }
 
     /**
-     * 移动视角。
+     * 移动白板视野。
      *
-     * 该方法可用于实现用户通过触屏手势对白板视野进行缩放操作的功能。
+     * 该方法可用于实现用户通过触屏手势对白板视野进行缩放和移动操作的功能。//TODO WJ 缩放功能是不是要求 disableCameraTrannsform 设置为 true？
      *
-     * @param camera 移动视角的具体参数配置，详见 {@link CameraConfig}。
+     * @param camera 白板视野的具体参数配置，详见 {@link CameraConfig}。
      * @since 2.2.0
      */
     public void moveCamera(CameraConfig camera) {
         this.bridge.callHandler("displayer.moveCamera", new Object[]{camera});
     }
 
     /**
-     * 调整用户视野。
+     * 调整用户视野。//TODO WJ 这个方法的描述是不是应该提到视觉矩形？
      *
      * @param rectangle 能表示用户视野的视觉矩形设置，详见 {@link RectangleConfig}。
      * @since 2.2.0

Android--CN/sdk/Player.java

@@ -45,7 +45,7 @@ public double getPlaybackSpeed() {
     /**
      * 设置白板回放的倍速。
      *
-     * @param playbackSpeed 白板回放的倍速。取值必须大于 0，设为 1 表示按原速播放。
+     * @param playbackSpeed 白板回放的倍速。取值必须大于 0，设为 1 表示按原速播放。//TODO WJ 这个取值没有上限吗？
      *
      * @since 2.5.2
      */
@@ -139,9 +139,9 @@ public void stop() {
     /**
      * 设置白板回放的开始时间。
      *
-     * 由于 SDK 会录制实时房间的全部过程，因此默认情况下，回放会播放从房间构造开始直到最后一次活跃结束的全部过程。
+     * 由于 SDK 会录制实时房间的全部过程，因此默认情况下，回放会播放从房间构造开始直到最后一次活跃结束的全部过程。//TODO WJ 最后一次活跃？
      * 因此在进行回放时，需要调用该方法设置开始回放的时间点。
-     * @param seekTime 白板回放的开始时间，单位为毫秒。
+     * @param seekTime 白板回放的开始时间，单位为毫秒。//TODO WJ 这个是 UTC 时间吗？
      */
     public void seekToScheduleTime(long seekTime) {
         bridge.callHandler("player.seekToScheduleTime", new Object[]{seekTime});
@@ -186,7 +186,7 @@ public void setObserverMode(PlayerObserverMode mode) {
     //region Get API
 
     /**
-     * 获取白板回放房间的阶段。该方法为同步调用。
+     * 获取白板回放房间的阶段。该方法为同步调用。//TODO WJ 上面几个方法都是“白板回放”，这里是“白板回放房间”，下面又变成“回放房间”，不知道是不是一回事。
      *
      * 在 Player 生命周期内，你可以调用该方法获取当前回放房间的阶段。其中初始阶段为 `waitingFirstFrame`，表示正在等待白板回放的第一帧。
      *
@@ -206,7 +206,7 @@ public PlayerPhase getPlayerPhase() {
      *
      * @note
      * - 成功调用 {@link #stop()}、{@link #play()}、{@link #pause()} 等方法均会影响回放房间的阶段，但是该阶段不会立即更新。
-     * - 该方位为异步调用。我们推荐你仅在调试或问题排查时使用。一般情况下可以使用同步方法 {@link #getPlayerPhase()} 进行获取。
+     * - 该方位为异步调用。我们推荐你仅在调试或问题排查时使用。一般情况下可以使用同步方法 {@link #getPlayerPhase()} 获取回放阶段。
      *
      * @param promise `Promise<PlayerPhase>` 接口实例，详见 {@link Promise 类}。你可以通过该接口了解获取白板回放阶段的结果：
      * - 如果获取成功，将返回白板回放的阶段。
@@ -234,7 +234,7 @@ public void onValue(Object o) {
     /**
      * 获取回放房间的状态。该方法为同步调用。
      *
-     * 如果回放房间的状态 Player phase 为 `waitingFirstFrame`，则该方法返回 Null。
+     * 如果回放房间的状态为 `waitingFirstFrame`，则该方法返回 `null`。
      *
      * @return 回放房间状态，详见 {@link PlayerState}。
      * @since 2.4.0
@@ -278,7 +278,7 @@ public void onValue(Object o) {
     /**
      * 获取白板回放的时间信息，该方法为同步调用。
      *
-     * 该方法获取的时间信息，包含当前的播放时间，回放文件的总时长，以及开始播放的 UTC 时间戳，单位为毫秒。
+     * 该方法获取的时间信息，包含当前的播放时间，回放文件的总时长，以及开始播放的 UTC 时间戳，单位为毫秒。//TODO WJ 当前的播放时间是指当前播放到哪里了？
      *
      * @note 该方法获取的当前播放时间可能不准确。
      *

Android--CN/sdk/PlayerEventListener.java

@@ -5,45 +5,45 @@
 import com.herewhite.sdk.domain.SDKError;
 
 /**
- * 回放房间事件回调接口
+ * 回放房间的事件回调接口。
  */
 public interface PlayerEventListener {
     /**
-     * 播放状态切换回调
+     * 播放状态切换回调。
      */
     void onPhaseChanged(PlayerPhase phase);
 
     /**
-     * 首帧加载回调
+     * 首帧加载回调。
      */
     void onLoadFirstFrame();
 
     /**
-     * 分片切换回调，需要了解分片机制。目前无实际用途
+     * 分片切换回调，需要了解分片机制。目前无实际用途。//TODO WJ 这个要放到文档里吗？
      */
     void onSliceChanged(String slice);
 
     /**
-     * 播放中，状态出现变化的回调，只会包含实际发生改变的属性
+     * 回放状态发生变化的回调，只会包含实际发生改变的属性。
      */
     void onPlayerStateChanged(PlayerState modifyState);
 
     /**
-     * 出错暂停
+     * 出错导致回放暂停的回调。
      */
     void onStoppedWithError(SDKError error);
 
     /**
-     * 进度时间变化
+     * 进度时间变化 //TODO WJ 这个是什么意思？
      */
     void onScheduleTimeChanged(long time);
 
     /**
-     * 添加帧出错
+     * 添加帧出错的回调。
      */
     void onCatchErrorWhenAppendFrame(SDKError error);
     /**
-     * 渲染时，出错
+     * 渲染时出错的回调。
      */
     void onCatchErrorWhenRender(SDKError error);
 }

Android--CN/sdk/domain/Appliance.java

@@ -6,24 +6,24 @@
 
 /** 教具名称。 */
 public class Appliance {
-    /** 铅笔 */
+    /** 铅笔。 */
     public final static String PENCIL = "pencil";
-    /** 选择工具 */
+    /** 选择工具。 */
     public final static String SELECTOR = "selector";
-    /** 矩形工具 */
+    /** 矩形工具。 */
     public final static String RECTANGLE = "rectangle";
-    /** 椭圆工具 */
+    /** 椭圆工具。 */
     public final static String ELLIPSE = "ellipse";
-    /** 橡皮工具 */
+    /** 橡皮工具。 */
     public final static String ERASER = "eraser";
-    /** 文本输入框 */
+    /** 文本输入框。 */
     public final static String TEXT = "text";
-    /** 直线工具 */
+    /** 直线工具。 */
     public final static String STRAIGHT = "straight";
-    /** 箭头工具 */
+    /** 箭头工具。 */
     public final static String ARROW = "arrow";
-    /** 抓手工具 */
+    /** 抓手工具。 */
     public final static String HAND = "hand";
-    /** 激光笔 */
+    /** 激光笔。 */
     public final static String LASER_POINTER = "laserPointer";
 }