document endpoint categories, start documentation of each endpoint, add helper in LinkedResult

Signed-off-by: Adam Ratzman <adam@adamratzman.com>

Author: adamint

README.md

@@ -3,8 +3,8 @@ This is the [Kotlin](https://kotlinlang.org/) implementation of the [Spotify Web
 
 ## Contents
   1. **[Downloading](#downloading)**
-  2. **[Creating a SpotifyAPI or SpotifyClientAPI object](#creating-a-spotifyAPI-or-spotifyClientAPI-object)**
-  3. **[What is the SpotifyRestAction class?](#what-is-the-spotifyRestAction-class?)**
+  2. **[Creating a SpotifyAPI or SpotifyClientAPI object](#creating-a-spotifyapi-or-spotifyclientapi-object)**
+  3. **[What is the SpotifyRestAction class?](#what-is-the-spotifyrestaction-class?)**
   4. **[Using the Library](#using-the-library)**
 
 ## Downloading
@@ -76,6 +76,9 @@ time, this will likely be accurate within a few milliseconds.
 - `asFuture()` transforms the supplier into a `CompletableFuture` 
 
 ## Using the Library
+### The benefits of LinkedResults, PagingObjects, and Cursor-based Paging Objects
+tbd
+
 ### Generic Request
 ```kotlin
     val api = SpotifyAPI.Builder("appId", "appSecret").build()
@@ -95,6 +98,9 @@ time, this will likely be accurate within a few milliseconds.
     }
 ```
 
+### Track Relinking
+tbd
+
 ### Endpoint List
 #### SpotifyAPI:
    - **[AlbumAPI (SpotifyAPI.albums)](https://developer.spotify.com/web-api/album-endpoints/)**
@@ -136,4 +142,44 @@ time, this will likely be accurate within a few milliseconds.
         5. `getAudioFeatures(vararg trackIds: String)` returns an ordered list of AudioFeatures. Time is *not* linear by track amount
    - **[PublicUserAPI (SpotifyAPI.users)](https://developer.spotify.com/web-api/user-profile-endpoints/)**
         1. `getProfile` returns the corresponding SpotifyPublicUser object. Pay attention to nullable parameters.
-   to be continued..
+#### SpotifyClientAPI:
+Make sure your application has requested the proper [Scopes](https://developer.spotify.com/web-api/using-scopes/) in order to 
+ensure proper function of this library.
+
+Check to see which Scope is necessary with the corresponding endpoint using the 
+links provided for each API below
+   - **[PersonalizationAPI (SpotifyClientAPI.personalization)](https://developer.spotify.com/web-api/web-api-personalization-endpoints/)**
+        1. `getTopArtists` returns an Artist `PagingObject` representing the most played Artists by the user
+        2. `getTopTracks` returns a Track `PagingObject` representing the most played Tracks by the user
+   - **[ClientUserAPI (SpotifyClientAPI.userProfile)](https://developer.spotify.com/web-api/user-profile-endpoints/)**
+        1. `getUserInformation` returns SpotifyUserInformation object, a much more detailed version of the public user object.
+   - **[UserLibraryAPI (SpotifyClientAPI.userLibrary)](https://developer.spotify.com/web-api/library-endpoints/)**
+        1. `getSavedTracks` returns a `PagingObject` of saved tracks in the user's library
+        2. `getSavedAlbums` returns a `PagingObject` of saved albums in the user's library
+        3. `savedTracksContains` returns an ordered List of Booleans of whether the track exists in the user's library 
+        corresponding to entered ids
+        4. `savedAlbumsContains` returns an ordered List of Booleans of whether the album exists in the user's library 
+        corresponding to entered ids.
+        5. `saveTracks` saves the entered tracks to the user's library. Returns nothing
+        6. `saveAlbums` saves the entered albums to the user's library. Returns nothing
+        7. `removeSavedTracks` removes the entered tracks from the user's library. Nothing happens if the track is not found. Returns nothing
+        8. `removeSavedAlbums` removes the entered albums from the user's library. Nothing happens if the album is not found in the library. Returns nothing
+   - **[FollowingAPI (SpotifyClientAPI.userFollowing)](https://developer.spotify.com/web-api/web-api-follow-endpoints/)**
+        1. `followingUsers` returns an ordered List of Booleans representing if the user follows the specified users
+        2. `followingArtists` returns an ordered List of Booleans representing if the user follows the specified artists
+        3. `getFollowedArtists` returns a [Cursor-Based Paging Object](https://developer.spotify.com/web-api/object-model/#cursor-based-paging-object) of followed Artists.
+        4. `followUsers` follows the specified users. Cannot be used with artists. Returns nothing
+        5. `followArtists` follows the specified artists. Cannot be mixed with users. Returns nothing
+        6. `followPlaylist` follows the specified playlist. Returns nothing
+        7. `unfollowUsers` unfollows the specified users. Cannot be used with artists. Returns nothing
+        8. `unfollowArtists` unfollows the specified artists. Cannot be mixed with users. Returns nothing
+        9. `unfollowPlaylist` unfollows the specified playlist. Returns nothing
+   - **[PlayerAPI (SpotifyClientAPI.player)](https://developer.spotify.com/web-api/web-api-connect-endpoint-reference/)**
+        The methods in this API are in beta and in flux as per Spotify. They will be documented in the near future.
+   - **[ClientPlaylistsAPI (SpotifyClientAPI.clientPlaylists)](https://developer.spotify.com/web-api/playlist-endpoints/)**
+        1. `createPlaylist` creates the playlist and returns its full Playlist representation
+        2. `addTrackToPlaylist` adds the entered tracks to the playlist. Returns nothing
+        3. `changePlaylistDescription` changes the description of the playlist. Returns nothing
+        4. `getUserPlaylists` returns a `PagingObject` of SimplePlaylists the user has created
+        5. `reorderTracks` reorders the tracks in the playlist and returns the current Snapshot
+        6. `replaceTracks` replaces tracks in the playlist and returns the current Snapshot

…fy/endpoints/priv/follow/FollowingAPI.kt …y/endpoints/priv/follow/UserFollowAPI.ktsrc/main/kotlin/com/adamratzman/spotify/endpoints/priv/follow/FollowingAPI.kt renamed to src/main/kotlin/com/adamratzman/spotify/endpoints/priv/follow/UserFollowAPI.kt src/main/kotlin/com/adamratzman/spotify/endpoints/priv/follow/FollowingAPI.kt renamed to src/main/kotlin/com/adamratzman/spotify/endpoints/priv/follow/UserFollowAPI.kt

@@ -4,7 +4,10 @@ import com.adamratzman.spotify.main.SpotifyAPI
 import com.adamratzman.spotify.utils.*
 import java.util.function.Supplier
 
-class FollowingAPI(api: SpotifyAPI) : SpotifyEndpoint(api) {
+/**
+ * These endpoints allow you manage the artists, users and playlists that a Spotify user follows.
+ */
+class UserFollowAPI(api: SpotifyAPI) : SpotifyEndpoint(api) {
     fun followingUsers(vararg userIds: String): SpotifyRestAction<List<Boolean>> {
         return toAction(Supplier {
             get("https://api.spotify.com/v1/me/following/contains?type=user&ids=${userIds.joinToString(",") { it.encode() }} { it.encode() }}").toObject<List<Boolean>>(api)

src/main/kotlin/com/adamratzman/spotify/endpoints/priv/library/UserLibraryAPI.kt

@@ -4,6 +4,9 @@ import com.adamratzman.spotify.main.SpotifyAPI
 import com.adamratzman.spotify.utils.*
 import java.util.function.Supplier
 
+/**
+ * Endpoints for retrieving information about, and managing, tracks that the current user has saved in their “Your Music” library.
+ */
 class UserLibraryAPI(api: SpotifyAPI) : SpotifyEndpoint(api) {
     fun getSavedTracks(): SpotifyRestAction<PagingObject<SavedTrack>> {
         return toAction(Supplier {

src/main/kotlin/com/adamratzman/spotify/endpoints/priv/personalization/PersonalizationAPI.kt

@@ -4,6 +4,9 @@ import com.adamratzman.spotify.main.SpotifyAPI
 import com.adamratzman.spotify.utils.*
 import java.util.function.Supplier
 
+/**
+ * Endpoints for retrieving information about the user’s listening habits.
+ */
 class PersonalizationAPI(api: SpotifyAPI) : SpotifyEndpoint(api) {
     fun getTopArtists(): SpotifyRestAction<PagingObject<Artist>> {
         return toAction(Supplier {

src/main/kotlin/com/adamratzman/spotify/endpoints/priv/player/PlayerAPI.kt

@@ -5,7 +5,8 @@ import com.adamratzman.spotify.utils.*
 import java.util.function.Supplier
 
 /**
- * This endpoint is in beta per the spotify documentation. These methods may or may not work
+ * These endpoints allow for viewing and controlling user playback. Please view [the official documentation](https://developer.spotify.com/web-api/working-with-connect/)
+ * for more information on how this works. This is in beta and is available for **premium users only**. Endpoints are **not** guaranteed to work
  */
 class PlayerAPI(api: SpotifyAPI) : SpotifyEndpoint(api) {
     fun getDevices(): SpotifyRestAction<List<Device>> {

…nts/priv/playlists/ClientPlaylistsAPI.kt …points/priv/playlists/UserPlaylistAPI.ktsrc/main/kotlin/com/adamratzman/spotify/endpoints/priv/playlists/ClientPlaylistsAPI.kt renamed to src/main/kotlin/com/adamratzman/spotify/endpoints/priv/playlists/UserPlaylistAPI.kt src/main/kotlin/com/adamratzman/spotify/endpoints/priv/playlists/ClientPlaylistsAPI.kt renamed to src/main/kotlin/com/adamratzman/spotify/endpoints/priv/playlists/UserPlaylistAPI.kt

@@ -5,7 +5,10 @@ import com.adamratzman.spotify.utils.*
 import org.json.JSONObject
 import java.util.function.Supplier
 
-class ClientPlaylistsAPI(api: SpotifyAPI) : SpotifyEndpoint(api) {
+/**
+ * Endpoints for retrieving information about a user’s playlists and for managing a user’s playlists.
+ */
+class UserPlaylistAPI(api: SpotifyAPI) : SpotifyEndpoint(api) {
     fun createPlaylist(userId: String, name: String, description: String, public: Boolean = true): SpotifyRestAction<Playlist> {
         return toAction(Supplier {
             post("https://api.spotify.com/v1/users/${userId.encode()}/playlists",

…fy/endpoints/priv/users/ClientUserAPI.kt …/spotify/endpoints/priv/users/UserAPI.ktsrc/main/kotlin/com/adamratzman/spotify/endpoints/priv/users/ClientUserAPI.kt renamed to src/main/kotlin/com/adamratzman/spotify/endpoints/priv/users/UserAPI.kt src/main/kotlin/com/adamratzman/spotify/endpoints/priv/users/ClientUserAPI.kt renamed to src/main/kotlin/com/adamratzman/spotify/endpoints/priv/users/UserAPI.kt

@@ -7,7 +7,10 @@ import com.adamratzman.spotify.utils.SpotifyUserInformation
 import com.adamratzman.spotify.utils.toObject
 import java.util.function.Supplier
 
-class ClientUserAPI(api: SpotifyAPI) : SpotifyEndpoint(api) {
+/**
+ * Endpoints for retrieving information about a user’s profile.
+ */
+class UserAPI(api: SpotifyAPI) : SpotifyEndpoint(api) {
     fun getUserProfile(): SpotifyRestAction<SpotifyUserInformation> {
         return toAction(Supplier {
             get("https://api.spotify.com/v1/me").toObject<SpotifyUserInformation>(api)

src/main/kotlin/com/adamratzman/spotify/endpoints/pub/album/AlbumAPI.kt

@@ -5,21 +5,45 @@ import com.adamratzman.spotify.utils.*
 import java.util.function.Supplier
 import java.util.stream.Collectors
 
+/**
+ * Endpoints for retrieving information about one or more albums from the Spotify catalog.
+ */
 class AlbumAPI(api: SpotifyAPI) : SpotifyEndpoint(api) {
+    /**
+     * Get Spotify catalog information for a single album.
+     * @param albumId The Spotify ID for the album.
+     * @param market Provide this parameter if you want to apply [Track Relinking](https://github.com/adamint/spotify-web-api-kotlin/blob/master/README.md#track-relinking)
+     *
+     * @throws BadRequestException if the [albumId] is not found
+     */
     fun getAlbum(albumId: String, market: Market? = null): SpotifyRestAction<Album> {
         return toAction(Supplier {
             get("https://api.spotify.com/v1/albums/$albumId${if (market != null) "?market=${market.code}" else ""}").toObject<Album>(api)
         })
     }
 
-    fun getAlbums(market: Market? = null, vararg albumIds: String): SpotifyRestAction<List<Album>> {
+    /**
+     * Get Spotify catalog information for multiple albums identified by their Spotify IDs. **Albums not found are returned as null inside the ordered list**
+     * @param albumIds List of the Spotify IDs for the albums.
+     * @param market Provide this parameter if you want to apply [Track Relinking](https://github.com/adamint/spotify-web-api-kotlin/blob/master/README.md#track-relinking)
+     */
+    fun getAlbums(vararg albumIds: String, market: Market? = null): SpotifyRestAction<List<Album?>> {
         if (albumIds.isEmpty()) throw BadRequestException(ErrorObject(404, "You cannot send a request with no album ids!"))
         return toAction(Supplier {
             get("https://api.spotify.com/v1/albums?ids=${albumIds.map { it.encode() }.toList().stream().collect(Collectors.joining(","))}${if (market != null) "&market=${market.code}" else ""}")
                     .toObject<AlbumsResponse>(api).albums
         })
     }
 
+    /**
+     * Get Spotify catalog information about an album’s tracks. Optional parameters can be used to limit the number of tracks returned.
+     * @param albumId The Spotify ID for the album.
+     * @param limit The maximum number of tracks to return. Default: 20. Minimum: 1. Maximum: 50.
+     * @param offset The index of the first track to return. Default: 0 (the first object). Use with limit to get the next set of tracks.
+     * @param market Provide this parameter if you want to apply [Track Relinking](https://github.com/adamint/spotify-web-api-kotlin/blob/master/README.md#track-relinking)
+     *
+     * @throws BadRequestException if the [albumId] is not found, or positioning of [limit] or [offset] is illegal.
+     */
     fun getAlbumTracks(albumId: String, limit: Int = 20, offset: Int = 0, market: Market? = null): SpotifyRestAction<LinkedResult<SimpleTrack>> {
         return toAction(Supplier {
             get("https://api.spotify.com/v1/albums/${albumId.encode()}/tracks?limit=$limit&offset=$offset${if (market != null) "&market=${market.code}" else ""}").toLinkedResult<SimpleTrack>(api)

src/main/kotlin/com/adamratzman/spotify/endpoints/pub/artists/ArtistsAPI.kt

@@ -5,37 +5,67 @@ import com.adamratzman.spotify.utils.*
 import java.util.function.Supplier
 import java.util.stream.Collectors
 
+/**
+ * Endpoints for retrieving information about one or more artists from the Spotify catalog.
+ */
 class ArtistsAPI(api: SpotifyAPI) : SpotifyEndpoint(api) {
+    /**
+     * Get Spotify catalog information for a single artist identified by their unique Spotify ID.
+     * @param artistId The Spotify ID for the artist.
+     *
+     * @throws BadRequestException if the [artistId] is not found
+     */
     fun getArtist(artistId: String): SpotifyRestAction<Artist> {
         return toAction(Supplier {
             get("https://api.spotify.com/v1/artists/${artistId.encode()}").toObject<Artist>(api)
         })
 
     }
 
-    fun getArtists(vararg artistIds: String): SpotifyRestAction<List<Artist>> {
+    /**
+     * Get Spotify catalog information for several artists based on their Spotify IDs. **Artists not found are returned as null inside the ordered list**
+     * @param artistIds List of the Spotify IDs representing the artists.
+     */
+    fun getArtists(vararg artistIds: String): SpotifyRestAction<List<Artist?>> {
         return toAction(Supplier {
             get("https://api.spotify.com/v1/artists?ids=${artistIds.map { it.encode() }.toList().stream().collect(Collectors.joining(","))}")
-                    .toObject<ArtistPNList>(api).artists
+                    .toObject<ArtistList>(api).artists
         })
     }
 
-    fun getArtistAlbums(artistId: String): SpotifyRestAction<LinkedResult<SimpleAlbum>> {
+    /**
+     * Get Spotify catalog information about an artist’s albums.
+     * @param artistId Spotify ID for the artist
+     * @param market Supply this parameter to limit the response to one particular geographical market.
+     * @param limit The number of album objects to return. Default: 20. Minimum: 1. Maximum: 50.
+     * @param offset The index of the first album to return. Default: 0 (i.e., the first album). Use with limit to get the next set of albums.
+     * @param include List of keywords that will be used to filter the response. If not supplied, all album groups will be returned.
+     *
+     * @throws BadRequestException if [artistId] is not found, or filter parameters are illegal
+     */
+    fun getArtistAlbums(artistId: String, market: Market?, limit: Int = 20, offset: Int = 0, vararg include: AlbumInclusionStrategy): SpotifyRestAction<LinkedResult<SimpleAlbum>> {
         return toAction(Supplier {
-            get("https://api.spotify.com/v1/artists/${artistId.encode()}/albums").toLinkedResult<SimpleAlbum>(api)
+            get("https://api.spotify.com/v1/artists/${artistId.encode()}/albums?limit=$limit&offset=$offset" +
+                    if (market != null) "&market=${market.code}" else "" +
+                            if (include.isNotEmpty()) "&include_groups=${include.joinToString(",") { it.keyword }}" else "")
+                    .toLinkedResult<SimpleAlbum>(api)
         })
     }
 
+    enum class AlbumInclusionStrategy(val keyword: String) {
+        ALBUM("album"), SINGLE("single"), APPEARS_ON("appears_on"), COMPILATION("compilation")
+    }
+
     fun getArtistTopTracks(artistId: String, market: Market): SpotifyRestAction<List<Track>> {
         return toAction(Supplier {
-            get("https://api.spotify.com/v1/artists/${artistId.encode()}/top-tracks?country=${market.code}").toObject<TrackList>(api).tracks
+            get("https://api.spotify.com/v1/artists/${artistId.encode()}/top-tracks?country=${market.code}").toObject<TrackList>(api).tracks.map { it!! }
         })
 
     }
 
     fun getRelatedArtists(artistId: String): SpotifyRestAction<List<Artist>> {
         return toAction(Supplier {
-            get("https://api.spotify.com/v1/artists/${artistId.encode()}/related-artists").toObject<ArtistList>(api).artists
+            get("https://api.spotify.com/v1/artists/${artistId.encode()}/related-artists").toObject<ArtistList>(api).artists.map { it!! }
         })
 
     }

src/main/kotlin/com/adamratzman/spotify/endpoints/pub/browse/BrowseAPI.kt

@@ -5,6 +5,9 @@ import com.adamratzman.spotify.utils.*
 import java.util.function.Supplier
 import java.util.stream.Collectors
 
+/**
+ * Endpoints for getting playlists and new album releases featured on Spotify’s Browse tab.
+ */
 class BrowseAPI(api: SpotifyAPI) : SpotifyEndpoint(api) {
     fun getNewReleases(limit: Int = 20, offset: Int = 0, market: Market? = null): SpotifyRestAction<PagingObject<Album>> {
         return toAction(Supplier {