public artists api documentation

Author: adamint

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

@@ -43,7 +43,7 @@ class ArtistsAPI(api: SpotifyAPI) : SpotifyEndpoint(api) {
      *
      * @throws BadRequestException if [artistId] is not found, or filter parameters are illegal
      */
-    fun getArtistAlbums(artistId: String, market: Market? = null, limit: Int = 20, offset: Int = 0, vararg include: AlbumInclusionStrategy): SpotifyRestAction<LinkedResult<SimpleAlbum>> {
+    fun getArtistAlbums(artistId: String, market: Market? = null, limit: Int = 20, offset: Int = 0, include: List<AlbumInclusionStrategy> = listOf()): SpotifyRestAction<LinkedResult<SimpleAlbum>> {
         return toAction(Supplier {
             get("https://api.spotify.com/v1/artists/${artistId.encode()}/albums?limit=$limit&offset=$offset" +
                     if (market != null) "&market=${market.code}" else "" +
@@ -56,13 +56,29 @@ class ArtistsAPI(api: SpotifyAPI) : SpotifyEndpoint(api) {
         ALBUM("album"), SINGLE("single"), APPEARS_ON("appears_on"), COMPILATION("compilation")
     }
 
+    /**
+     * Get Spotify catalog information about an artist’s top tracks **by country**.
+     * @param artistId 	The Spotify ID for the artist.
+     * @param market The country ([Market]) to search. Unlike endpoints with optional Track Relinking, the Market is **not** optional.
+     *
+     * @throws BadRequestException if tracks are not available in the specified [Market] or the [artistId] is not found
+     */
     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.map { it!! }
         })
 
     }
 
+    /**
+     * Get Spotify catalog information about artists similar to a given artist.
+     * Similarity is based on analysis of the Spotify community’s listening history.
+     *
+     * @param artistId    The Spotify ID for the artist.
+     *
+     * @return List of *never-null*, but possibly empty Artist objects representing similar artists
+     * @throws BadRequestException if the [artistId] is not found
+     */
     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.map { it!! }

src/test/kotlin/com/adamratzman/spotify/endpoints/pub/artists/ArtistsAPITest.kt

@@ -1,5 +1,6 @@
 package com.adamratzman.spotify.kotlin.endpoints.pub.artists
 
+import com.adamratzman.spotify.endpoints.pub.artists.ArtistsAPI
 import com.adamratzman.spotify.main.api
 import com.adamratzman.spotify.utils.BadRequestException
 import com.adamratzman.spotify.utils.Market
@@ -15,7 +16,8 @@ class ArtistsAPITest : TestCase() {
     }
 
     fun testGetArtistAlbums() {
-        println(api.artists.getArtistAlbums("0C8ZW7ezQVs4URX5aX7Kqx").complete())
+        println(api.artists.getArtistAlbums("0C8ZW7ezQVs4URX5aX7Kqx",
+                include = listOf(ArtistsAPI.AlbumInclusionStrategy.ALBUM, ArtistsAPI.AlbumInclusionStrategy.SINGLE)).complete())
     }
 
     fun testGetArtistTopTracks() {