From 87727070e9afed45306b151efd405f201dac0b32 Mon Sep 17 00:00:00 2001
From: "jacek.wolniewicz" <jacekwoln@gmail.com>
Date: Mon, 1 Jul 2024 21:33:04 +0200
Subject: [PATCH] Move all events documentation to the 'EventsBuilder'

---
 .../data/events/TikTokCommentEvent.java       |  4 +-
 .../data/events/TikTokConnectedEvent.java     |  3 -
 .../data/events/TikTokDisconnectedEvent.java  |  5 +-
 .../tiktok/data/events/TikTokErrorEvent.java  |  3 -
 .../data/events/TikTokLiveEndedEvent.java     |  4 +-
 .../data/events/TikTokQuestionEvent.java      |  4 +-
 .../data/events/TikTokSubscribeEvent.java     |  4 +-
 .../data/events/common/TikTokEvent.java       |  3 -
 .../control/TikTokPreConnectionEvent.java     |  4 +-
 .../events/gift/TikTokGiftComboEvent.java     | 14 +---
 .../data/events/gift/TikTokGiftEvent.java     |  6 +-
 .../data/events/room/TikTokRoomInfoEvent.java |  4 +-
 .../data/events/social/TikTokFollowEvent.java |  4 +-
 .../data/events/social/TikTokLikeEvent.java   |  4 +-
 .../data/events/social/TikTokShareEvent.java  |  4 +-
 .../TikTokWebsocketMessageEvent.java          |  5 +-
 .../TikTokWebsocketUnhandledMessageEvent.java |  4 +-
 .../tiktok/live/builder/EventsBuilder.java    | 77 ++++++++++++++++++-
 18 files changed, 88 insertions(+), 68 deletions(-)

diff --git a/API/src/main/java/io/github/jwdeveloper/tiktok/data/events/TikTokCommentEvent.java b/API/src/main/java/io/github/jwdeveloper/tiktok/data/events/TikTokCommentEvent.java
index 16b51eb..91dd6a0 100644
--- a/API/src/main/java/io/github/jwdeveloper/tiktok/data/events/TikTokCommentEvent.java
+++ b/API/src/main/java/io/github/jwdeveloper/tiktok/data/events/TikTokCommentEvent.java
@@ -32,9 +32,7 @@ import lombok.Getter;
 
 import java.util.List;
 
-/**
- * Triggered every time a new chat comment arrives.
- */
+
 @Getter
 @EventMeta(eventType = EventType.Message)
 public class TikTokCommentEvent extends TikTokHeaderEvent {
diff --git a/API/src/main/java/io/github/jwdeveloper/tiktok/data/events/TikTokConnectedEvent.java b/API/src/main/java/io/github/jwdeveloper/tiktok/data/events/TikTokConnectedEvent.java
index cf8e1ed..b81ccdb 100644
--- a/API/src/main/java/io/github/jwdeveloper/tiktok/data/events/TikTokConnectedEvent.java
+++ b/API/src/main/java/io/github/jwdeveloper/tiktok/data/events/TikTokConnectedEvent.java
@@ -25,9 +25,6 @@ import io.github.jwdeveloper.tiktok.annotations.EventMeta;
 import io.github.jwdeveloper.tiktok.annotations.EventType;
 import io.github.jwdeveloper.tiktok.data.events.common.TikTokLiveClientEvent;
 
-/**
- * Triggered when the connection is successfully established.
- */
 @EventMeta(eventType = EventType.Control)
 public class TikTokConnectedEvent extends TikTokLiveClientEvent
 {
diff --git a/API/src/main/java/io/github/jwdeveloper/tiktok/data/events/TikTokDisconnectedEvent.java b/API/src/main/java/io/github/jwdeveloper/tiktok/data/events/TikTokDisconnectedEvent.java
index 6e5d11a..d15e14a 100644
--- a/API/src/main/java/io/github/jwdeveloper/tiktok/data/events/TikTokDisconnectedEvent.java
+++ b/API/src/main/java/io/github/jwdeveloper/tiktok/data/events/TikTokDisconnectedEvent.java
@@ -26,10 +26,7 @@ import io.github.jwdeveloper.tiktok.annotations.EventType;
 import io.github.jwdeveloper.tiktok.data.events.common.TikTokLiveClientEvent;
 import lombok.Getter;
 
-/**
- * Triggered when the connection gets disconnected. In that case you can call connect() again to have a reconnect logic.
- * Note that you should wait a little bit before attempting a reconnect to to avoid being rate-limited.
- */
+
 @Getter
 @EventMeta(eventType = EventType.Control)
 public class TikTokDisconnectedEvent extends TikTokLiveClientEvent {
diff --git a/API/src/main/java/io/github/jwdeveloper/tiktok/data/events/TikTokErrorEvent.java b/API/src/main/java/io/github/jwdeveloper/tiktok/data/events/TikTokErrorEvent.java
index c3cedf7..1374eeb 100644
--- a/API/src/main/java/io/github/jwdeveloper/tiktok/data/events/TikTokErrorEvent.java
+++ b/API/src/main/java/io/github/jwdeveloper/tiktok/data/events/TikTokErrorEvent.java
@@ -28,9 +28,6 @@ import io.github.jwdeveloper.tiktok.data.events.common.TikTokLiveClientEvent;
 import lombok.AllArgsConstructor;
 import lombok.Getter;
 
-/**
- * General error event. You should handle this.
- */
 @Getter
 @AllArgsConstructor
 @EventMeta(eventType = EventType.Control)
diff --git a/API/src/main/java/io/github/jwdeveloper/tiktok/data/events/TikTokLiveEndedEvent.java b/API/src/main/java/io/github/jwdeveloper/tiktok/data/events/TikTokLiveEndedEvent.java
index 20a4e71..93af1f7 100644
--- a/API/src/main/java/io/github/jwdeveloper/tiktok/data/events/TikTokLiveEndedEvent.java
+++ b/API/src/main/java/io/github/jwdeveloper/tiktok/data/events/TikTokLiveEndedEvent.java
@@ -26,9 +26,7 @@ import io.github.jwdeveloper.tiktok.annotations.EventType;
 import io.github.jwdeveloper.tiktok.data.events.common.TikTokEvent;
 
 
-/**
- * Triggered when the live stream gets terminated by the host. Will also trigger the TikTokDisconnectedEvent event.
- */
+
 @EventMeta(eventType = EventType.Message)
 public class TikTokLiveEndedEvent extends TikTokEvent {
 }
diff --git a/API/src/main/java/io/github/jwdeveloper/tiktok/data/events/TikTokQuestionEvent.java b/API/src/main/java/io/github/jwdeveloper/tiktok/data/events/TikTokQuestionEvent.java
index 3570463..56cb0a0 100644
--- a/API/src/main/java/io/github/jwdeveloper/tiktok/data/events/TikTokQuestionEvent.java
+++ b/API/src/main/java/io/github/jwdeveloper/tiktok/data/events/TikTokQuestionEvent.java
@@ -29,9 +29,7 @@ import io.github.jwdeveloper.tiktok.data.models.users.User;
 import io.github.jwdeveloper.tiktok.messages.webcast.WebcastQuestionNewMessage;
 import lombok.Getter;
 
-/*
-Triggered every time someone asks a new question via the question feature.
- */
+
 @Getter
 @EventMeta(eventType = EventType.Message)
 public class TikTokQuestionEvent extends TikTokHeaderEvent {
diff --git a/API/src/main/java/io/github/jwdeveloper/tiktok/data/events/TikTokSubscribeEvent.java b/API/src/main/java/io/github/jwdeveloper/tiktok/data/events/TikTokSubscribeEvent.java
index fde3819..b4a07c1 100644
--- a/API/src/main/java/io/github/jwdeveloper/tiktok/data/events/TikTokSubscribeEvent.java
+++ b/API/src/main/java/io/github/jwdeveloper/tiktok/data/events/TikTokSubscribeEvent.java
@@ -31,9 +31,7 @@ import io.github.jwdeveloper.tiktok.messages.webcast.WebcastMemberMessage;
 import io.github.jwdeveloper.tiktok.messages.webcast.WebcastSubNotifyMessage;
 import lombok.Getter;
 
-/**
- * Triggers when a user creates a subscription.
- */
+
 @Getter
 @EventMeta(eventType = EventType.Message)
 public class TikTokSubscribeEvent extends TikTokHeaderEvent {
diff --git a/API/src/main/java/io/github/jwdeveloper/tiktok/data/events/common/TikTokEvent.java b/API/src/main/java/io/github/jwdeveloper/tiktok/data/events/common/TikTokEvent.java
index 1c01ec5..36c7f23 100644
--- a/API/src/main/java/io/github/jwdeveloper/tiktok/data/events/common/TikTokEvent.java
+++ b/API/src/main/java/io/github/jwdeveloper/tiktok/data/events/common/TikTokEvent.java
@@ -26,9 +26,6 @@ package io.github.jwdeveloper.tiktok.data.events.common;
 import io.github.jwdeveloper.tiktok.utils.JsonUtil;
 import lombok.Getter;
 
-/**
- * Base class for all events
- */
 @Getter
 public abstract class TikTokEvent {
 
diff --git a/API/src/main/java/io/github/jwdeveloper/tiktok/data/events/control/TikTokPreConnectionEvent.java b/API/src/main/java/io/github/jwdeveloper/tiktok/data/events/control/TikTokPreConnectionEvent.java
index 64cf958..282772b 100644
--- a/API/src/main/java/io/github/jwdeveloper/tiktok/data/events/control/TikTokPreConnectionEvent.java
+++ b/API/src/main/java/io/github/jwdeveloper/tiktok/data/events/control/TikTokPreConnectionEvent.java
@@ -27,9 +27,7 @@ import io.github.jwdeveloper.tiktok.data.events.common.TikTokLiveClientEvent;
 import io.github.jwdeveloper.tiktok.data.requests.*;
 import lombok.*;
 
-/**
- * Triggered before the connection is established.
- */
+
 @Getter
 @EventMeta(eventType = EventType.Control)
 public class TikTokPreConnectionEvent extends TikTokLiveClientEvent
diff --git a/API/src/main/java/io/github/jwdeveloper/tiktok/data/events/gift/TikTokGiftComboEvent.java b/API/src/main/java/io/github/jwdeveloper/tiktok/data/events/gift/TikTokGiftComboEvent.java
index f992ecb..849a12b 100644
--- a/API/src/main/java/io/github/jwdeveloper/tiktok/data/events/gift/TikTokGiftComboEvent.java
+++ b/API/src/main/java/io/github/jwdeveloper/tiktok/data/events/gift/TikTokGiftComboEvent.java
@@ -30,19 +30,7 @@ import io.github.jwdeveloper.tiktok.messages.webcast.WebcastGiftMessage;
 import lombok.Getter;
 
 
-/**
- * Triggered every time gift is sent
- *
- * @see GiftComboStateType it has 3 states
- *
- * <p>Example when user sends gift with combo</p>
- * <p>>Combo: 1  -> comboState = GiftSendType.Begin</p>
- * <p>Combo: 4 -> comboState = GiftSendType.Active</p>
- * <p>Combo: 8 -> comboState = GiftSendType.Active</p>
- * <p>Combo: 12 -> comboState = GiftSendType.Finished</p>
- * <p>
- * Remember if comboState is Finished both TikTokGiftComboEvent and TikTokGiftEvent event gets triggered
- */
+
 @EventMeta(eventType = EventType.Message)
 @Getter
 public class TikTokGiftComboEvent extends TikTokGiftEvent {
diff --git a/API/src/main/java/io/github/jwdeveloper/tiktok/data/events/gift/TikTokGiftEvent.java b/API/src/main/java/io/github/jwdeveloper/tiktok/data/events/gift/TikTokGiftEvent.java
index 3b3cd0b..caa3485 100644
--- a/API/src/main/java/io/github/jwdeveloper/tiktok/data/events/gift/TikTokGiftEvent.java
+++ b/API/src/main/java/io/github/jwdeveloper/tiktok/data/events/gift/TikTokGiftEvent.java
@@ -32,11 +32,7 @@ import io.github.jwdeveloper.tiktok.messages.webcast.WebcastGiftMessage;
 import lombok.Getter;
 
 
-/**
- * Triggered when user sends gifts that has
- * no combo (most of expensive gifts)
- * or if combo has finished
- */
+
 @EventMeta(eventType = EventType.Message)
 @Getter
 public class TikTokGiftEvent extends TikTokHeaderEvent {
diff --git a/API/src/main/java/io/github/jwdeveloper/tiktok/data/events/room/TikTokRoomInfoEvent.java b/API/src/main/java/io/github/jwdeveloper/tiktok/data/events/room/TikTokRoomInfoEvent.java
index 186e577..9e36497 100644
--- a/API/src/main/java/io/github/jwdeveloper/tiktok/data/events/room/TikTokRoomInfoEvent.java
+++ b/API/src/main/java/io/github/jwdeveloper/tiktok/data/events/room/TikTokRoomInfoEvent.java
@@ -30,9 +30,7 @@ import lombok.AllArgsConstructor;
 import lombok.Getter;
 
 
-/**
-Triggered when LiveRoomInfo got updated such as likes, viewers, ranking ....
- */
+
 @Getter
 @AllArgsConstructor
 @EventMeta(eventType = EventType.Message)
diff --git a/API/src/main/java/io/github/jwdeveloper/tiktok/data/events/social/TikTokFollowEvent.java b/API/src/main/java/io/github/jwdeveloper/tiktok/data/events/social/TikTokFollowEvent.java
index 351b9a8..4a5fbce 100644
--- a/API/src/main/java/io/github/jwdeveloper/tiktok/data/events/social/TikTokFollowEvent.java
+++ b/API/src/main/java/io/github/jwdeveloper/tiktok/data/events/social/TikTokFollowEvent.java
@@ -29,9 +29,7 @@ import io.github.jwdeveloper.tiktok.data.models.users.User;
 import io.github.jwdeveloper.tiktok.messages.webcast.WebcastSocialMessage;
 import lombok.Value;
 
-/**
- * Triggers when a user follows the streamer. Based on social event.
- */
+
 @Value
 @EventMeta(eventType = EventType.Message)
 public class TikTokFollowEvent extends TikTokHeaderEvent
diff --git a/API/src/main/java/io/github/jwdeveloper/tiktok/data/events/social/TikTokLikeEvent.java b/API/src/main/java/io/github/jwdeveloper/tiktok/data/events/social/TikTokLikeEvent.java
index ce93b44..c740928 100644
--- a/API/src/main/java/io/github/jwdeveloper/tiktok/data/events/social/TikTokLikeEvent.java
+++ b/API/src/main/java/io/github/jwdeveloper/tiktok/data/events/social/TikTokLikeEvent.java
@@ -31,9 +31,7 @@ import io.github.jwdeveloper.tiktok.messages.webcast.WebcastSocialMessage;
 import lombok.Getter;
 
 
-/**
- * Triggered when a viewer sends likes to the streamer. For streams with many viewers, this event is not always triggered by TikTok.
- */
+
 @Getter
 @EventMeta(eventType = EventType.Message)
 public class TikTokLikeEvent extends TikTokHeaderEvent
diff --git a/API/src/main/java/io/github/jwdeveloper/tiktok/data/events/social/TikTokShareEvent.java b/API/src/main/java/io/github/jwdeveloper/tiktok/data/events/social/TikTokShareEvent.java
index 7b80e11..9d0f6f9 100644
--- a/API/src/main/java/io/github/jwdeveloper/tiktok/data/events/social/TikTokShareEvent.java
+++ b/API/src/main/java/io/github/jwdeveloper/tiktok/data/events/social/TikTokShareEvent.java
@@ -29,9 +29,7 @@ import io.github.jwdeveloper.tiktok.data.models.users.User;
 import io.github.jwdeveloper.tiktok.messages.webcast.WebcastSocialMessage;
 import lombok.Getter;
 
-/**
- * Triggers when a user shares the stream. Based on social event.
- */
+
 @Getter
 @EventMeta(eventType = EventType.Message)
 public class TikTokShareEvent extends TikTokHeaderEvent {
diff --git a/API/src/main/java/io/github/jwdeveloper/tiktok/data/events/websocket/TikTokWebsocketMessageEvent.java b/API/src/main/java/io/github/jwdeveloper/tiktok/data/events/websocket/TikTokWebsocketMessageEvent.java
index 062db68..8aba618 100644
--- a/API/src/main/java/io/github/jwdeveloper/tiktok/data/events/websocket/TikTokWebsocketMessageEvent.java
+++ b/API/src/main/java/io/github/jwdeveloper/tiktok/data/events/websocket/TikTokWebsocketMessageEvent.java
@@ -35,10 +35,7 @@ import lombok.Value;
 import java.time.Duration;
 
 
-/**
- * Triggered every time TikTok sends data. Data incoming as protobuf message.
- * You can deserialize the binary object depending on the use case.
- */
+
 @Getter
 @AllArgsConstructor
 @EventMeta(eventType = EventType.Debug)
diff --git a/API/src/main/java/io/github/jwdeveloper/tiktok/data/events/websocket/TikTokWebsocketUnhandledMessageEvent.java b/API/src/main/java/io/github/jwdeveloper/tiktok/data/events/websocket/TikTokWebsocketUnhandledMessageEvent.java
index cdfccfc..acf1b48 100644
--- a/API/src/main/java/io/github/jwdeveloper/tiktok/data/events/websocket/TikTokWebsocketUnhandledMessageEvent.java
+++ b/API/src/main/java/io/github/jwdeveloper/tiktok/data/events/websocket/TikTokWebsocketUnhandledMessageEvent.java
@@ -29,9 +29,7 @@ import io.github.jwdeveloper.tiktok.messages.webcast.WebcastResponse;
 import lombok.Getter;
 
 
-/**
- * Triggered every time a protobuf encoded webcast message arrives. You can deserialize the binary object depending on the use case.
- */
+
 @Getter
 @EventMeta(eventType = EventType.Debug)
 public class TikTokWebsocketUnhandledMessageEvent extends TikTokUnhandledEvent<WebcastResponse.Message>
diff --git a/API/src/main/java/io/github/jwdeveloper/tiktok/live/builder/EventsBuilder.java b/API/src/main/java/io/github/jwdeveloper/tiktok/live/builder/EventsBuilder.java
index 961ff49..a6f4552 100644
--- a/API/src/main/java/io/github/jwdeveloper/tiktok/live/builder/EventsBuilder.java
+++ b/API/src/main/java/io/github/jwdeveloper/tiktok/live/builder/EventsBuilder.java
@@ -36,6 +36,7 @@ import io.github.jwdeveloper.tiktok.data.events.social.TikTokShareEvent;
 import io.github.jwdeveloper.tiktok.data.events.websocket.TikTokWebsocketMessageEvent;
 import io.github.jwdeveloper.tiktok.data.events.websocket.TikTokWebsocketResponseEvent;
 import io.github.jwdeveloper.tiktok.data.events.websocket.TikTokWebsocketUnhandledMessageEvent;
+import io.github.jwdeveloper.tiktok.data.models.gifts.GiftComboStateType;
 
 
 public interface EventsBuilder<T> {
@@ -101,7 +102,7 @@ public interface EventsBuilder<T> {
     }
 
     /**
-     * Invoked when there was not found event mapper for TikTok protocolBuffer data "message"
+     * Triggered every time a protobuf encoded webcast message arrives. You can deserialize the binary object depending on the use case.
      *
      * @param action consumable action
      * @return self instance
@@ -132,51 +133,120 @@ public interface EventsBuilder<T> {
     }
 
     /**
-     * Invoked for gifts that has combo options such as roses
+     * Triggered every time gift is sent
      *
      * @param action consumable action
      * @return self instance
+     * @see GiftComboStateType it has 3 states
+     *
+     * <p>Example when user sends gift with combo</p>
+     * <p>>Combo: 1  -> comboState = GiftSendType.Begin</p>
+     * <p>Combo: 4 -> comboState = GiftSendType.Active</p>
+     * <p>Combo: 8 -> comboState = GiftSendType.Active</p>
+     * <p>Combo: 12 -> comboState = GiftSendType.Finished</p>
+     * <p>
+     * Remember if comboState is Finished both TikTokGiftComboEvent and TikTokGiftEvent event gets triggered
      */
     default T onGiftCombo(EventConsumer<TikTokGiftComboEvent> action) {
         return onEvent(TikTokGiftComboEvent.class, action);
     }
 
+    /**
+     * Triggered every time someone asks a new question via the question feature.
+     *
+     * @param action consumable action
+     * @return self instance
+     */
     default T onQuestion(EventConsumer<TikTokQuestionEvent> action) {
         return onEvent(TikTokQuestionEvent.class, action);
     }
 
+    /**
+     * Triggers when a user subscribe the streamer.
+     *
+     * @param action consumable action
+     * @return self instance
+     */
     default T onSubscribe(EventConsumer<TikTokSubscribeEvent> action) {
         return onEvent(TikTokSubscribeEvent.class, action);
     }
 
+    /**
+     * Triggers when a user follows the streamer. Based on social event.
+     *
+     * @param action consumable action
+     * @return self instance
+     */
     default T onFollow(EventConsumer<TikTokFollowEvent> action) {
         return onEvent(TikTokFollowEvent.class, action);
     }
 
+    /**
+     * Triggered when a viewer sends likes to the streamer. For streams with many viewers, this event is not always triggered by TikTok.
+     *
+     * @param action consumable action
+     * @return self instance
+     */
     default T onLike(EventConsumer<TikTokLikeEvent> action) {
         return onEvent(TikTokLikeEvent.class, action);
     }
 
+    /**
+     * Triggers when a user sends emote
+     *
+     * @param action consumable action
+     * @return self instance
+     */
     default T onEmote(EventConsumer<TikTokEmoteEvent> action) {
         return onEvent(TikTokEmoteEvent.class, action);
     }
 
+    /**
+     * Triggers when a user joins to the live
+     *
+     * @param action consumable action
+     * @return self instance
+     */
     default T onJoin(EventConsumer<TikTokJoinEvent> action) {
         return onEvent(TikTokJoinEvent.class, action);
     }
 
+    /**
+     * Triggers when a user shares the stream.
+     *
+     * @param action consumable action
+     * @return self instance
+     */
     default T onShare(EventConsumer<TikTokShareEvent> action) {
         return onEvent(TikTokShareEvent.class, action);
     }
 
+    /**
+     * Triggered when the live stream gets paused
+     *
+     * @param action consumable action
+     * @return self instance
+     */
     default T onLivePaused(EventConsumer<TikTokLivePausedEvent> action) {
         return onEvent(TikTokLivePausedEvent.class, action);
     }
 
+    /**
+     * Triggered when the live stream gets unpaused
+     *
+     * @param action consumable action
+     * @return self instance
+     */
     default T onLiveUnpaused(EventConsumer<TikTokLiveUnpausedEvent> action) {
         return onEvent(TikTokLiveUnpausedEvent.class, action);
     }
 
+    /**
+     * Triggered when the live stream gets terminated by the host. Will also trigger the TikTokDisconnectedEvent event.
+     *
+     * @param action consumable action
+     * @return self instance
+     */
     default T onLiveEnded(EventConsumer<TikTokLiveEndedEvent> action) {
         return onEvent(TikTokLiveEndedEvent.class, action);
     }
@@ -212,7 +282,8 @@ public interface EventsBuilder<T> {
     }
 
     /**
-     * Invoked when client disconnected
+     * Triggered when the connection gets disconnected. In that case you can call connect() again to have a reconnect logic.
+     * Note that you should wait a little bit before attempting a reconnect to avoid being rate-limited.
      *
      * @param action consumable action
      * @return self instance