Update documentation

src/main/java/me/goudham/APIWrapper.java

@@ -11,6 +11,7 @@ import me.goudham.domain.waifu.WaifuImage;
 import me.goudham.exception.APIMapperException;
 import me.goudham.exception.APIResponseException;
 import me.goudham.util.Season;
+import me.goudham.util.WaifuListType;
 
 import java.io.IOException;
 import java.net.URI;
@@ -91,86 +92,239 @@ public class APIWrapper {
         }
     }
 
+    /**
+     * Retrieve detailed information about the {@link Waifu} by sending request to API
+     *
+     * @param waifuId The id of the {@link Waifu}
+     * @return {@link Response} of {@link Waifu}
+     * @throws APIResponseException If {@link APIWrapper} could not return information properly
+     * @throws APIMapperException If {@link APIMapper} could not correctly {@code deserialize} model
+     *
+     */
     Response<Waifu> getWaifu(String waifuId) throws APIResponseException, APIMapperException {
         Result waifuResult = sendRequest("waifu/" + waifuId);
         return apiMapper.deserialize(waifuResult, Waifu.class);
     }
 
+    /**
+     * Retrieve paginated images from the gallery, in sets of 10, by sending request to API
+     *
+     * @param waifuId The id of the {@link Waifu}
+     * @param pageNum The page number of the gallery
+     * @return {@link Response} of {@link WaifuImage}
+     * @throws APIResponseException If {@link APIWrapper} could not return information properly
+     * @throws APIMapperException If {@link APIMapper} could not correctly {@code deserialize} model
+     *
+     */
     Response<PaginationData<WaifuImage>> getWaifuImages(String waifuId, String pageNum) throws APIResponseException, APIMapperException {
         Result waifuImagesResult = sendRequest("waifu/" + waifuId + "/images?page=" + pageNum);
         return apiMapper.deserializeToPaginationData(waifuImagesResult, paginationData(WaifuImage.class));
     }
 
+    /**
+     * Retrieve an array of {@link FilteredWaifu}'s, sorted alphabetically, by sending request to API
+     *
+     * @param pageNum The page number of the gallery
+     * @return {@link Response} of {@link PaginationData} with {@link FilteredWaifu}
+     * @throws APIResponseException If {@link APIWrapper} could not return information properly
+     * @throws APIMapperException If {@link APIMapper} could not correctly {@code deserialize} model
+     *
+     */
     Response<PaginationData<FilteredWaifu>> getWaifusByPage(String pageNum) throws APIResponseException, APIMapperException {
         Result waifusByPageResult = sendRequest("waifu?page=" + pageNum);
         return apiMapper.deserializeToPaginationData(waifusByPageResult, paginationData(FilteredWaifu.class));
     }
 
+    /**
+     * Retrieve the Waifu of the Day by sending request to API
+     *
+     * @return {@link Response} of {@link FilteredWaifu}
+     * @throws APIResponseException If {@link APIWrapper} could not return information properly
+     * @throws APIMapperException If {@link APIMapper} could not correctly {@code deserialize} model
+     *
+     */
     Response<FilteredWaifu> getDailyWaifu() throws APIResponseException, APIMapperException {
         Result dailyWaifuResult = sendRequest("meta/daily");
         return apiMapper.deserialize(dailyWaifuResult, FilteredWaifu.class);
     }
 
+    /**
+     * Retrieve a Random Waifu from the Website by sending request to API
+     *
+     * @return {@link Response} of {@link FilteredWaifu}
+     * @throws APIResponseException If {@link APIWrapper} could not return information properly
+     * @throws APIMapperException If {@link APIMapper} could not correctly {@code deserialize} model
+     *
+     */
     Response<FilteredWaifu> getRandomWaifu() throws APIResponseException, APIMapperException {
         Result randomWaifuResult = sendRequest("meta/random");
         return apiMapper.deserialize(randomWaifuResult, FilteredWaifu.class);
     }
 
+    /**
+     * Retrieve a List of Currently Airing Anim by sending request to API
+     *
+     * @return {@link Response} of {@link List} with {@link FilteredSeries}
+     * @throws APIResponseException If {@link APIWrapper} could not return information properly
+     * @throws APIMapperException If {@link APIMapper} could not correctly {@code deserialize} model
+     *
+     */
     Response<List<FilteredSeries>> getSeasonalAnime() throws APIResponseException, APIMapperException {
         Result seasonalAnimeResult = sendRequest("airing");
         return apiMapper.deserializeToList(seasonalAnimeResult, listOf(FilteredSeries.class));
     }
 
+    /**
+     * Retrieve the Best Waifus of the Current Season by sending request to API
+     *
+     * @return {@link Response} of {@link List} with {@link FilteredWaifu}
+     * @throws APIResponseException If {@link APIWrapper} could not return information properly
+     * @throws APIMapperException If {@link APIMapper} could not correctly {@code deserialize} model
+     *
+     */
     Response<List<FilteredWaifu>> getBestWaifus() throws APIResponseException, APIMapperException {
         Result waifuResults = sendRequest("airing/best");
         return apiMapper.deserializeToList(waifuResults, listOf(FilteredWaifu.class));
     }
 
+    /**
+     * Retrieve a List of Popular Waifus <i>(Raw Count of Total Votes)</i> of the Current Season
+     * by sending request to API
+     *
+     * @return {@link Response} of {@link List} with {@link FilteredWaifu}
+     * @throws APIResponseException If {@link APIWrapper} could not return information properly
+     * @throws APIMapperException If {@link APIMapper} could not correctly {@code deserialize} model
+     *
+     */
     Response<List<FilteredWaifu>> getPopularWaifus() throws APIResponseException, APIMapperException {
         Result waifuResults = sendRequest("airing/popular");
         return apiMapper.deserializeToList(waifuResults, listOf(FilteredWaifu.class));
     }
 
+    /**
+     * Retrieve the Most Disliked Waifus of the Current Season by sending request to API
+     *
+     * @return {@link Response} of {@link List} with {@link FilteredWaifu}
+     * @throws APIResponseException If {@link APIWrapper} could not return information properly
+     * @throws APIMapperException If {@link APIMapper} could not correctly {@code deserialize} model
+     *
+     */
     Response<List<FilteredWaifu>> getTrashWaifus() throws APIResponseException, APIMapperException {
         Result waifuResults = sendRequest("airing/trash");
         return apiMapper.deserializeToList(waifuResults, listOf(FilteredWaifu.class));
     }
 
+    /**
+     * Retrieve detailed information about a given {@link Series} by sending request to API
+     *
+     * @param seriesId The id of the {@link Series}
+     * @return {@link Response} of {@link Series}
+     * @throws APIResponseException If {@link APIWrapper} could not return information properly
+     * @throws APIMapperException If {@link APIMapper} could not correctly {@code deserialize} model
+     *
+     */
     Response<Series> getSeries(String seriesId) throws APIResponseException, APIMapperException {
         Result seriesResult = sendRequest("series/" + seriesId);
         return apiMapper.deserialize(seriesResult, Series.class);
     }
 
+    /**
+     * Retrieve paginated information about a Series by sending request to API
+     *
+     * @param pageNum The page number of the gallery
+     * @return {@link Response} of {@link PaginationData} with {@link FilteredSeries}
+     * @throws APIResponseException If {@link APIWrapper} could not return information properly
+     * @throws APIMapperException If {@link APIMapper} could not correctly {@code deserialize} model
+     *
+     */
     Response<PaginationData<FilteredSeries>> getSeriesByPage(String pageNum) throws APIResponseException, APIMapperException {
         Result seriesPageResult = sendRequest("series?page=" + pageNum);
         return apiMapper.deserializeToPaginationData(seriesPageResult, paginationData(FilteredSeries.class));
     }
 
+    /**
+     * Retrieve the List of Anime that Aired in a given Season and Year by sending request to API
+     *
+     * @param season The specified season from {@link Season}
+     * @param year The specified year
+     * @return {@link Response} of {@link List} with {@link FilteredSeries}
+     * @throws APIResponseException If {@link APIWrapper} could not return information properly
+     * @throws APIMapperException If {@link APIMapper} could not correctly {@code deserialize} model
+     *
+     */
     Response<List<FilteredSeries>> getAllSeries(Season season, Integer year) throws APIResponseException, APIMapperException {
         Result allSeriesResult = sendRequest("airing/" + season.getSeason() + "/" + year);
         return apiMapper.deserializeToList(allSeriesResult, listOf(FilteredSeries.class));
     }
 
+    /**
+     * Retrieve a set of Waifus for a given {@link Series} by sending request to API
+     *
+     * @param seriesId The id of the {@link Series}
+     * @return {@link Response} of {@link List} with {@link FilteredWaifu}
+     * @throws APIResponseException If {@link APIWrapper} could not return information properly
+     * @throws APIMapperException If {@link APIMapper} could not correctly {@code deserialize} model
+     *
+     */
     Response<List<FilteredWaifu>> getSeriesWaifus(String seriesId) throws APIResponseException, APIMapperException {
         Result allWaifusFromSeriesResults = sendRequest("series/" + seriesId + "/waifus");
         return apiMapper.deserializeToList(allWaifusFromSeriesResults, listOf(FilteredWaifu.class));
     }
 
+    /**
+     * Retrieve information about the {@link User} by sending request to API
+     *
+     * @param userId The id of the {@link User}
+     * @return {@link Response} of {@link User}
+     * @throws APIResponseException If {@link APIWrapper} could not return information properly
+     * @throws APIMapperException If {@link APIMapper} could not correctly {@code deserialize} model
+     *
+     */
     Response<User> getUserProfile(String userId) throws APIResponseException, APIMapperException {
         Result userProfileResult = sendRequest("user/" + userId);
         return apiMapper.deserialize(userProfileResult, User.class);
     }
 
+    /**
+     * Retrieve the Waifus Created, Liked, or Trashed for the given {@link User} id by sending request to API
+     *
+     * @param userId The id of the {@link User}
+     * @param listType The specified action E.g {@link WaifuListType#LIKED}
+     * @param pageNum The page number of the gallery
+     * @return {@link Response} of {@link PaginationData} with {@link FilteredWaifu}
+     * @throws APIResponseException If {@link APIWrapper} could not return information properly
+     * @throws APIMapperException If {@link APIMapper} could not correctly {@code deserialize} model
+     *
+     */
     Response<PaginationData<FilteredWaifu>> getUserWaifus(String userId, String listType, String pageNum) throws APIResponseException, APIMapperException {
         Result userWaifusResult = sendRequest("user/" + userId + "/" + listType + "?page=" + pageNum);
         return apiMapper.deserializeToPaginationData(userWaifusResult, paginationData(FilteredWaifu.class));
     }
 
+    /**
+     * Retrieve a List of all {@link UserList}'s shown by sending request to API
+     *
+     * @param userId The id of the {@link User}
+     * @return {@link Response} of {@link List} with {@link UserList}
+     * @throws APIResponseException If {@link APIWrapper} could not return information properly
+     * @throws APIMapperException If {@link APIMapper} could not correctly {@code deserialize} model
+     *
+     */
     Response<List<UserList>> getUserLists(String userId) throws APIResponseException, APIMapperException {
         Result userProfileResult = sendRequest("user/" + userId + "/lists");
         return apiMapper.deserializeToList(userProfileResult, listOf(UserList.class));
     }
 
+    /**
+     * Retrieve the Specific {@link UserList}, with {@link Waifu}'s by sending request to API
+     *
+     * @param userId The id of the {@link User}
+     * @param listId The id of the {@link UserList}
+     * @return {@link Response} of {@link UserList}
+     * @throws APIResponseException If {@link APIWrapper} could not return information properly
+     * @throws APIMapperException If {@link APIMapper} could not correctly {@code deserialize} model
+     *
+     */
     Response<UserList> getUserList(String userId, String listId) throws APIResponseException, APIMapperException {
         Result userProfileResult = sendRequest("user/" + userId + "/lists/" + listId);
         return apiMapper.deserialize(userProfileResult, UserList.class);