Document ConferencesRequest, MessagesRequest and SendMessageRequest

Author: rubengees

library/src/main/java/com/proxerme/library/connection/messenger/entity/Conference.java

@@ -12,7 +12,8 @@
 import com.proxerme.library.interfaces.TimeItem;
 
 /**
- * TODO: Describe class
+ * Class representing a single conference. This might be a group chat or a conversation with a
+ * single user (indicated by {@link #isGroup()}.
  *
  * @author Ruben Gees
  */
@@ -55,6 +56,21 @@ public Conference[] newArray(int size) {
     Conference() {
     }
 
+    /**
+     * The constructor.
+     *
+     * @param id                  The id of this conference.
+     * @param topic               The topic.
+     * @param customTopic         A custom topic set by a user.
+     * @param participantAmount   The amount of participants in this conference.
+     * @param imageType           The type of the image. This is "avatar" in most cases.
+     * @param imageId             The id of the image.
+     * @param isGroup             Indicator if this is a group chat.
+     * @param isRead              Indicator if this conference has been read by the current user.
+     * @param time                The time of the last message in this conference.
+     * @param unreadMessageAmount The amount of unread messages for the current user.
+     * @param lastReadMessageId   The id of the last read message of the current user.
+     */
     public Conference(@NonNull String id, @NonNull String topic, @NonNull String customTopic,
                       @IntRange(from = 2) int participantAmount, @Nullable String imageType,
                       @Nullable String imageId, boolean isGroup, boolean isRead, long time,
@@ -90,11 +106,21 @@ protected Conference(Parcel in) {
         this.unreadMessageAmount = in.readInt();
     }
 
+    /**
+     * Returns the id of the last read message.
+     *
+     * @return The id.
+     */
     @NonNull
     public String getLastReadMessageId() {
         return lastReadMessageId;
     }
 
+    /**
+     * Returns the type of the image. Might be empty if there is no image.
+     *
+     * @return The image type.
+     */
     @NonNull
     public String getImageType() {
         String[] split = image.split(":");
@@ -106,6 +132,11 @@ public String getImageType() {
         }
     }
 
+    /**
+     * Returns the id of the image. Might be empty if there is no image.
+     *
+     * @return The id.
+     */
     @Override
     @NonNull
     public String getImageId() {
@@ -118,40 +149,80 @@ public String getImageId() {
         }
     }
 
+    /**
+     * Returns if this message has been read.
+     *
+     * @return True, if read.
+     */
     public boolean isRead() {
         return isRead;
     }
 
+    /**
+     * Returns the custom topic for this conference. Might be empty.
+     *
+     * @return The custom topic.
+     */
     @NonNull
     public String getCustomTopic() {
         return customTopic;
     }
 
+    /**
+     * Returns the amount of participants in this conference.
+     *
+     * @return The amount.
+     */
     @IntRange(from = 2)
     public int getParticipantAmount() {
         return participantAmount;
     }
 
+    /**
+     * Returns the topic of this conference.
+     *
+     * @return The topic.
+     */
     @NonNull
     public String getTopic() {
         return topic;
     }
 
+    /**
+     * Returns the id of this conference.
+     *
+     * @return The id.
+     */
     @Override
     @NonNull
     public String getId() {
         return id;
     }
 
+    /**
+     * Returns the time of the last message in this conference.
+     *
+     * @return The time.
+     */
     @Override
     public long getTime() {
         return time;
     }
 
+    /**
+     * Returns if this conference is a group chat.
+     *
+     * @return True, if it is a group chat.
+     */
     public boolean isGroup() {
         return isGroup;
     }
 
+    /**
+     * Returns the amount of unread messages.
+     *
+     * @return The amount of unread messages.
+     */
     @IntRange(from = 0)
     public int getUnreadMessageAmount() {
         return unreadMessageAmount;

library/src/main/java/com/proxerme/library/connection/messenger/entity/Message.java

@@ -9,7 +9,7 @@
 import com.proxerme.library.interfaces.TimeItem;
 
 /**
- * TODO: Describe class
+ * Class that represents a single message.
  *
  * @author Ruben Gees
  */
@@ -48,6 +48,19 @@ public Message[] newArray(int size) {
     Message() {
     }
 
+    /**
+     * The constructor.
+     *
+     * @param id           The id of this message.
+     * @param conferenceId The id of the conference this message belongs to.
+     * @param userId       The id of the user, who sent this message.
+     * @param username     The username of the user, who sent this message.
+     * @param message      The contents of the message.
+     * @param action       The action of this message. This might be something like "addUser". Might be
+     *                     empty if there is no action.
+     * @param time         The time this message was sent.
+     * @param device       The device this message was sent from. In most cases "default".
+     */
     public Message(@NonNull String id, @NonNull String conferenceId, @NonNull String userId,
                    @NonNull String username, @NonNull String message, @NonNull String action,
                    long time, @NonNull String device) {
@@ -72,42 +85,74 @@ protected Message(Parcel in) {
         this.device = in.readString();
     }
 
+    /**
+     * Returns the id of this message.
+     * @return The id.
+     */
     @NonNull
     @Override
     public String getId() {
         return id;
     }
 
+    /**
+     * Returns the id of the conference this message belongs to.
+     * @return The id.
+     */
     @NonNull
     public String getConferenceId() {
         return conferenceId;
     }
 
+    /**
+     * Returns the id of the user.
+     * @return The id.
+     */
     @NonNull
     public String getUserId() {
         return userId;
     }
 
+    /**
+     * Returns the username of the user.
+     * @return The username.
+     */
     @NonNull
     public String getUsername() {
         return username;
     }
 
+    /**
+     * Returns the actual contents of this message.
+     * @return The contents of this message.
+     */
     @NonNull
     public String getMessage() {
         return message;
     }
 
+    /**
+     * Returns the action of this message. Might be empty.
+     * @return The action.
+     */
     @NonNull
     public String getAction() {
         return action;
     }
 
+    /**
+     * Returns the time of this message.
+     * @return The time.
+     */
     @Override
     public long getTime() {
         return time;
     }
 
+    /**
+     * Returns the device this message was sent from.
+     * @return The device.
+     */
     @NonNull
     public String getDevice() {
         return device;

library/src/main/java/com/proxerme/library/connection/messenger/request/ConferencesRequest.java

@@ -14,7 +14,8 @@
 import static com.proxerme.library.info.ProxerTag.MESSENGER_CONFERENCES;
 
 /**
- * TODO: Describe class
+ * Request for the conferences of the user. The user must be logged in for this API to return data.
+ * This API uses pagination.
  *
  * @author Ruben Gees
  */
@@ -29,10 +30,21 @@ public class ConferencesRequest extends ProxerRequest<ConferencesResult> {
     private int page;
     private String type;
 
+    /**
+     * The constructor.
+     *
+     * @param page The page to load.
+     */
     public ConferencesRequest(@IntRange(from = 0) int page) {
         this.page = page;
     }
 
+    /**
+     * The type to load.
+     *
+     * @param type The type.
+     * @return This Request.
+     */
     public ConferencesRequest withType(@Nullable @ConferenceType String type) {
         this.type = type;
 

library/src/main/java/com/proxerme/library/connection/messenger/request/MessagesRequest.java

@@ -11,7 +11,17 @@
 import static com.proxerme.library.info.ProxerTag.MESSENGER_MESSAGES;
 
 /**
- * TODO: Describe class
+ * Request for loading messages. There are 4 different cases associated with the conferenceId and
+ * messageId:
+ * <p>
+ * 1) conferenceId = "0" and messageId = "0". The latest messages of the user are loaded.
+ * 2) conferenceId = "0" and messageId = X. The messages before the specified id are loaded.
+ * 3) conferenceId = X and messageId = "0". The latest messages in the specified conference are
+ * loaded.
+ * 4) conferenceId = X and messageId = X. The messages before the specified messageId in the
+ * specified conference are loaded.
+ * <p>
+ * This API requires the user to be logged in.
  *
  * @author Ruben Gees
  */
@@ -26,6 +36,12 @@ public class MessagesRequest extends ProxerRequest<MessagesResult> {
     private String conferenceId;
     private String messageId;
 
+    /**
+     * The constructor.
+     *
+     * @param conferenceId The id of the conference to load from.
+     * @param messageId    The id of the message to load previous messages from.
+     */
     public MessagesRequest(@NonNull String conferenceId, @NonNull String messageId) {
         this.conferenceId = conferenceId;
         this.messageId = messageId;

library/src/main/java/com/proxerme/library/connection/messenger/request/SendMessageRequest.java

@@ -10,7 +10,7 @@
 import com.proxerme.library.info.ProxerUrlHolder;
 
 /**
- * TODO: Describe class
+ * Request for sending a single message. This API requires the user to be logged in.
  *
  * @author Ruben Gees
  */
@@ -25,6 +25,12 @@ public class SendMessageRequest extends ProxerRequest<SendMessageResult> {
     private String conferenceId;
     private String text;
 
+    /**
+     * The constructor.
+     *
+     * @param conferenceId The conference to send the message to.
+     * @param text         The contents of the message.
+     */
     public SendMessageRequest(@NonNull String conferenceId, @NonNull String text) {
         this.conferenceId = conferenceId;
         this.text = text;

library/src/main/java/com/proxerme/library/connection/messenger/result/ConferencesResult.java

@@ -7,7 +7,7 @@
 import com.proxerme.library.interfaces.ProxerResult;
 
 /**
- * TODO: Describe class
+ * Result of a {@link com.proxerme.library.connection.messenger.request.ConferencesRequest}.
  *
  * @author Ruben Gees
  */
@@ -20,10 +20,19 @@ public class ConferencesResult implements ProxerResult<Conference[]> {
     ConferencesResult() {
     }
 
+    /**
+     * The constructor.
+     *
+     * @param item The array of received conferences.
+     */
     public ConferencesResult(@NonNull Conference[] item) {
         this.item = item;
     }
 
+    /**
+     * Returns the array of retrieved conferences.
+     * @return The array of conferences.
+     */
     @Override
     public Conference[] getItem() {
         return item;

library/src/main/java/com/proxerme/library/connection/messenger/result/MessagesResult.java

@@ -7,7 +7,7 @@
 import com.proxerme.library.interfaces.ProxerResult;
 
 /**
- * TODO: Describe class
+ * Result of a {@link com.proxerme.library.connection.messenger.request.MessagesRequest}.
  *
  * @author Ruben Gees
  */
@@ -20,10 +20,19 @@ public class MessagesResult implements ProxerResult<Message[]> {
     MessagesResult() {
     }
 
+    /**
+     * The constructor.
+     *
+     * @param item The array of retrieved messages.
+     */
     public MessagesResult(@NonNull Message[] item) {
         this.item = item;
     }
 
+    /**
+     * Returns the array of retrieved messages.
+     * @return The array of messages.
+     */
     @Override
     @NonNull
     public Message[] getItem() {