From 5cc27f5560c05befdee8cbd6db24fc0eaab87cb3 Mon Sep 17 00:00:00 2001
From: Pinapelz <donaldshan1@outlook.com>
Date: Fri, 7 Apr 2023 15:21:53 -0700
Subject: Added Javadoc comments

---
 src/main/java/com/pina/Holodex.java                | 67 ++++++++++++++++-
 src/main/java/com/pina/HolodexException.java       | 14 ++++
 src/main/java/com/pina/HolodexService.java         | 87 ++++++++++++++++++++++
 src/main/java/com/pina/datatypes/Channel.java      |  3 +
 src/main/java/com/pina/datatypes/Comment.java      |  3 +
 .../java/com/pina/datatypes/SimpleChannel.java     |  3 +
 src/main/java/com/pina/datatypes/SimpleVideo.java  |  3 +
 src/main/java/com/pina/datatypes/Video.java        |  3 +
 .../java/com/pina/query/ChannelQueryBuilder.java   |  6 +-
 .../com/pina/query/VideoByVideoIdQueryBuilder.java |  7 +-
 .../java/com/pina/query/VideoQueryBuilder.java     |  7 +-
 .../pina/query/VideosByChannelIDQueryBuilder.java  |  6 +-
 12 files changed, 194 insertions(+), 15 deletions(-)

(limited to 'src')

diff --git a/src/main/java/com/pina/Holodex.java b/src/main/java/com/pina/Holodex.java
index 931021f..9e7ef39 100644
--- a/src/main/java/com/pina/Holodex.java
+++ b/src/main/java/com/pina/Holodex.java
@@ -17,15 +17,28 @@ import retrofit2.converter.jackson.JacksonConverterFactory;
 import java.io.IOException;
 import java.util.List;
 
+/**
+ * The class for interacting with the Holodex API
+ */
 public class Holodex {
     private HolodexService service;
 
+    /**
+     * Instantiates a new Holodex with the default base url
+     *
+     * @param apiKey the api key
+     */
     public Holodex(String apiKey) {
         initializeHolodexService(apiKey, "https://holodex.net");
     }
 
+    /**
+     * Instantiates a new Holodex with a custom base url
+     *
+     * @param apiKey  the api key
+     * @param baseUrl the base url
+     */
     public Holodex(String apiKey, String baseUrl) {
-        // purely for unit testing
         initializeHolodexService(apiKey, baseUrl);
     }
 
@@ -47,6 +60,13 @@ public class Holodex {
         service = retrofit.create(HolodexService.class);
     }
 
+    /**
+     * Gets a list of upcoming and/or live SimpleVideos matching the VideoQueryBuilder attributes
+     *
+     * @param queryBuilder the query builder
+     * @return A list of upcoming and/or live SimpleVideos
+     * @throws HolodexException the holodex exception
+     */
     public List<SimpleVideo> getLiveAndUpcomingVideos(VideoQueryBuilder queryBuilder) throws HolodexException {
         Call<List<SimpleVideo>> call = service.getLiveVideos(queryBuilder.getChannelId(), queryBuilder.getId(),
                 queryBuilder.getInclude(), queryBuilder.getLang(),
@@ -59,6 +79,13 @@ public class Holodex {
         return executeCall(call);
     }
 
+    /**
+     * Gets a list of videos matching the VideoQueryBuilder attributes
+     *
+     * @param queryBuilder the query builder
+     * @return list of videos
+     * @throws HolodexException the holodex exception
+     */
     public List<Video> getVideos(VideoQueryBuilder queryBuilder) throws HolodexException {
         Call<List<Video>> call = service.getVideos(queryBuilder.getChannelId(), queryBuilder.getId(),
                 queryBuilder.getInclude(), queryBuilder.getLang(),
@@ -71,11 +98,26 @@ public class Holodex {
         return executeCall(call);
     }
 
+    /**
+     * Gets information about a channel when given a channel id
+     *
+     * @param channelId the channel id
+     * @return the Channel
+     * @throws HolodexException the holodex exception
+     */
     public Channel getChannel(String channelId) throws HolodexException {
         Call<Channel> call = service.getChannel(channelId);
         return executeCall(call);
     }
 
+    /**
+     * Gets a list of Videos matching the VideoByVideoIdQueryBuilder attributes for a specific channel
+     * Used for when the channel id is known
+     *
+     * @param query the query
+     * @return List of videos matching the query
+     * @throws HolodexException the holodex exception
+     */
     public List<Video> getVideosByChannelId(VideosByChannelIDQueryBuilder query) throws HolodexException {
         Call<List<Video>> call = service.getVideosByChannelId(query.getChannelId(), query.getType(), query.getInclude(),
                 query.getLang(), query.getLimit(), query.getOffset(), query.getPaginated());
@@ -83,17 +125,40 @@ public class Holodex {
 
     }
 
+    /**
+     * Gets upcoming and live videos from an array of channel ids
+     * Response will contain videos from all channels together
+     * This should be used when there is a set of channels that need to be queried
+     *
+     * @param channels the channel ids to get videos from
+     * @return List of live and/or upcoming videos where the channel id is the author
+     * @throws HolodexException the holodex exception
+     */
     public List<Video> getVideosFromChannels(String[] channels) throws HolodexException{
         String channelsString = String.join(",", channels);
         Call<List<Video>> call = service.getVideosFromChannels(channelsString);
         return executeCall(call);
     }
 
+    /**
+     * Gets the video matching the VideoByVideoIdQueryBuilder attributes
+     *
+     * @param query the query
+     * @return Video matching the query
+     * @throws HolodexException holodex exception
+     */
     public Video getVideo(VideoByVideoIdQueryBuilder query) throws HolodexException {
         Call<Video> call = service.getVideo(query.getVideoId(), query.getLang(), query.getC());
         return executeCall(call);
     }
 
+    /**
+     * Gets a list of channels the match the ChannelQueryBuilder attributes
+     *
+     * @param query the query
+     * @return List of channels matching the query
+     * @throws HolodexException the holodex exception
+     */
     public List<Channel> getChannels(ChannelQueryBuilder query) throws HolodexException{
         Call<List<Channel>> call = service.getChannels(query.getLimit(), query.getOffset(), query.getType(),
                 query.getLang(), query.getOrder(), query.getOrg(), query.getSort()
diff --git a/src/main/java/com/pina/HolodexException.java b/src/main/java/com/pina/HolodexException.java
index 8dc8cbd..e6adc2f 100644
--- a/src/main/java/com/pina/HolodexException.java
+++ b/src/main/java/com/pina/HolodexException.java
@@ -1,10 +1,24 @@
 package com.pina;
 
+/**
+ * Class for Holodex related exceptions
+ */
 public class HolodexException extends Exception{
+    /**
+     * Instantiates a new Holodex exception.
+     *
+     * @param message the message
+     */
     public HolodexException(String message) {
         super(message);
     }
 
+    /**
+     * Instantiates a new Holodex exception.
+     *
+     * @param message the message
+     * @param cause   the cause
+     */
     public HolodexException(String message, Throwable cause) {
         super(message, cause);
     }
diff --git a/src/main/java/com/pina/HolodexService.java b/src/main/java/com/pina/HolodexService.java
index fa2af85..c7cad0e 100644
--- a/src/main/java/com/pina/HolodexService.java
+++ b/src/main/java/com/pina/HolodexService.java
@@ -10,7 +10,30 @@ import retrofit2.http.Query;
 
 import java.util.List;
 
+/**
+ * The interface Holodex service.
+ */
 public interface HolodexService {
+    /**
+     * /api/v2/live endpoint
+     *
+     * @param channel_id           the YouTube channel id
+     * @param id                   the YouTube video id
+     * @param include              the include parameters
+     * @param lang                 a comma separated String of languages (e.g "en,ja")
+     * @param limit                the limit for the number of results
+     * @param maxUpcomingHours     number of maximum hours to show upcoming videos
+     * @param mentioned_channel_id the mentioned channel id of a different channel (for collabs)
+     * @param offset               the offset for the number of results
+     * @param order                the order (asc, desc)
+     * @param org                  the organization of which to get videos for (e.g. "Hololive")
+     * @param paginated            paginated field
+     * @param sort                 sort by returned field (e.g "start_scheduled")
+     * @param status               filter by video status (e.g. "upcoming")
+     * @param topic                filter by type of video (e.g "stream")
+     * @param type                 the type
+     * @return a list of SimpleVideo objects
+     */
     @GET("/api/v2/live")
     Call<List<SimpleVideo>> getLiveVideos(
             @Query("channel_id") String channel_id,
@@ -30,6 +53,26 @@ public interface HolodexService {
             @Query("type") String type
     );
 
+    /**
+     * /api/v2/video endpoint
+     *
+     * @param channel_id           the YouTube channel id
+     * @param id                   the YouTube video id
+     * @param include              the include parameters comma seperated
+     * @param lang                 a comma separated String of languages (e.g "en,ja")
+     * @param limit                the limit for the number of results
+     * @param max_upcoming_hours   number of maximum hours to show upcoming videos
+     * @param mentioned_channel_id the mentioned channel id of a different channel (for collabs)
+     * @param offset               the offset for the number of results
+     * @param order                the order (asc, desc)
+     * @param org                  the organization of which to get videos for (e.g. "Hololive")
+     * @param paginated            paginated field
+     * @param sort                 sort by returned field (e.g "start_scheduled")
+     * @param status               filter by video status (e.g. "upcoming")
+     * @param topic                filter by type of video (e.g "stream")
+     * @param type                 the type
+     * @return a list of Video objects
+     */
     @GET("/api/v2/videos")
     Call<List<Video>> getVideos(
             @Query("channel_id") String channel_id,
@@ -49,11 +92,29 @@ public interface HolodexService {
             @Query("type") String type
     );
 
+    /**
+     * /api/v2/channels endpoint
+     *
+     * @param channelID the channel id
+     * @return the channel
+     */
     @GET("/api/v2/channels/{channelID}")
     Call<Channel> getChannel(
             @Path("channelID") String channelID
     );
 
+    /**
+     * /api/v2/channels/{channelID}/{type} endpoint
+     *
+     * @param channelID     the YouTube channel id
+     * @param type          the type of video resource ("clips", "videos", "collabs")
+     * @param include       the include parameters comma seperated
+     * @param lang          a comma separated String of languages (e.g "en,ja")
+     * @param limit         the limit for the number of results
+     * @param offset        the offset for the number of results
+     * @param paginated     paginated field
+     * @return list of Videos by channel id
+     */
     @GET("/api/v2/channels/{channelID}/{type}")
     Call<List<Video>> getVideosByChannelId(
             @Path("channelID") String channelID,
@@ -65,11 +126,25 @@ public interface HolodexService {
             @Query("paginated") String paginated
     );
 
+    /**
+     * /api/v2/users/live endpoint
+     *
+     * @param channels the channel ids in a comma separated String
+     * @return the videos from channels
+     */
     @GET("/api/v2/users/live")
     Call<List<Video>> getVideosFromChannels(
             @Query("channels") String channels
     );
 
+    /**
+     * /api/v2/videos/{videoID} endpoint
+     *
+     * @param videoID the YouTube video id
+     * @param lang    a comma separated String of languages (e.g "en,ja")
+     * @param c       1 will return timestamp comments for the video, 0 will not
+     * @return the video
+     */
     @GET("/api/v2/videos/{videoID}")
     Call<Video> getVideo(
             @Path("videoID") String videoID,
@@ -77,6 +152,18 @@ public interface HolodexService {
             @Query("c") String c
     );
 
+    /**
+     * /api/v2/channels endpoint
+     *
+     * @param limit  the limit for the number of results
+     * @param offset the offset for the number of results
+     * @param type   the type of channel (e.g "vtuber")
+     * @param lang   a comma separated String of languages (e.g "en,ja")
+     * @param order  ascending or descending order (e.g "asc")
+     * @param org    filter by organization (e.g "Hololive")
+     * @param sort   column in which data should be sorted (default is org)
+     * @return the channels
+     */
     @GET("/api/v2/channels")
     Call<List<Channel>> getChannels(
             @Query("limit") Integer limit,
diff --git a/src/main/java/com/pina/datatypes/Channel.java b/src/main/java/com/pina/datatypes/Channel.java
index cadfbc9..3b88ffa 100644
--- a/src/main/java/com/pina/datatypes/Channel.java
+++ b/src/main/java/com/pina/datatypes/Channel.java
@@ -2,6 +2,9 @@ package com.pina.datatypes;
 
 import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
 
+/**
+ * Channel object
+ */
 @JsonIgnoreProperties(ignoreUnknown = true)
 public class Channel extends SimpleChannel{
     public String suborg;
diff --git a/src/main/java/com/pina/datatypes/Comment.java b/src/main/java/com/pina/datatypes/Comment.java
index cf52a1f..d145227 100644
--- a/src/main/java/com/pina/datatypes/Comment.java
+++ b/src/main/java/com/pina/datatypes/Comment.java
@@ -1,5 +1,8 @@
 package com.pina.datatypes;
 
+/**
+ * Comment object
+ */
 public class Comment {
     public String comment_key;
     public String video_id;
diff --git a/src/main/java/com/pina/datatypes/SimpleChannel.java b/src/main/java/com/pina/datatypes/SimpleChannel.java
index c70a0be..caff399 100644
--- a/src/main/java/com/pina/datatypes/SimpleChannel.java
+++ b/src/main/java/com/pina/datatypes/SimpleChannel.java
@@ -2,6 +2,9 @@ package com.pina.datatypes;
 
 import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
 
+/**
+ * Simple channel object
+ */
 @JsonIgnoreProperties(ignoreUnknown = true)
 public class SimpleChannel {
     public String id;
diff --git a/src/main/java/com/pina/datatypes/SimpleVideo.java b/src/main/java/com/pina/datatypes/SimpleVideo.java
index 1d30748..c373605 100644
--- a/src/main/java/com/pina/datatypes/SimpleVideo.java
+++ b/src/main/java/com/pina/datatypes/SimpleVideo.java
@@ -2,6 +2,9 @@ package com.pina.datatypes;
 
 import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
 
+/**
+ * Simple video object
+ */
 @JsonIgnoreProperties (ignoreUnknown = true)
 public class SimpleVideo {
     public String id;
diff --git a/src/main/java/com/pina/datatypes/Video.java b/src/main/java/com/pina/datatypes/Video.java
index 850dfb9..05be300 100644
--- a/src/main/java/com/pina/datatypes/Video.java
+++ b/src/main/java/com/pina/datatypes/Video.java
@@ -5,6 +5,9 @@ import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
 
 import java.util.List;
 
+/**
+ * Video object
+ */
 @JsonIgnoreProperties(ignoreUnknown = true)
 public class Video extends SimpleVideo {
     public List<Video> clips;
diff --git a/src/main/java/com/pina/query/ChannelQueryBuilder.java b/src/main/java/com/pina/query/ChannelQueryBuilder.java
index 1c51d68..85035d7 100644
--- a/src/main/java/com/pina/query/ChannelQueryBuilder.java
+++ b/src/main/java/com/pina/query/ChannelQueryBuilder.java
@@ -1,9 +1,9 @@
 package com.pina.query;
 
+/**
+ * Query builder for getting a list of Channels matching the given parameters
+ */
 public class ChannelQueryBuilder {
-    /***
-     * Used to get a set of channels matching the given parameters
-     */
     private Integer limit;
     private Integer offset;
     private String type;
diff --git a/src/main/java/com/pina/query/VideoByVideoIdQueryBuilder.java b/src/main/java/com/pina/query/VideoByVideoIdQueryBuilder.java
index b996028..917cf49 100644
--- a/src/main/java/com/pina/query/VideoByVideoIdQueryBuilder.java
+++ b/src/main/java/com/pina/query/VideoByVideoIdQueryBuilder.java
@@ -1,10 +1,9 @@
 package com.pina.query;
 
-
+/**
+ * Query builder for getting a video by video id
+ */
 public class VideoByVideoIdQueryBuilder {
-    /***
-     * Used to get the metadata of a single video when given the video ID
-     */
     private String videoId;
     private String lang;
     private String c;
diff --git a/src/main/java/com/pina/query/VideoQueryBuilder.java b/src/main/java/com/pina/query/VideoQueryBuilder.java
index 67acd1b..ecf211c 100644
--- a/src/main/java/com/pina/query/VideoQueryBuilder.java
+++ b/src/main/java/com/pina/query/VideoQueryBuilder.java
@@ -1,10 +1,9 @@
 package com.pina.query;
 
+/**
+ * Query builder for getting a set of videos matching the given parameters
+ */
 public class VideoQueryBuilder {
-    /***
-     * Query parameters for /api/v2/live and /api/v2/videos
-     * Query Live and Upcoming Videos
-     */
     private String channelId;
     private String id;
     private String include;
diff --git a/src/main/java/com/pina/query/VideosByChannelIDQueryBuilder.java b/src/main/java/com/pina/query/VideosByChannelIDQueryBuilder.java
index 0ba9963..43720f9 100644
--- a/src/main/java/com/pina/query/VideosByChannelIDQueryBuilder.java
+++ b/src/main/java/com/pina/query/VideosByChannelIDQueryBuilder.java
@@ -1,9 +1,9 @@
 package com.pina.query;
 
+/**
+ * Query builder for getting videos by a given channel id
+ */
 public class VideosByChannelIDQueryBuilder {
-    /***
-     * Used to get the videos of a single channel when given the channel ID
-     */
     private String channelId;
     private String type;
     private String include;
-- 
cgit v1.2.3