Merge pull request #47 from adamint/documentation

Documentation

Author: adamint

build.gradle

@@ -1,9 +1,12 @@
 buildscript {
     ext.kotlin_version = '1.3.11'
+    ext.dokka_version = '0.9.17'
+
     repositories { jcenter() }
 
     dependencies {
         classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
+        classpath "org.jetbrains.dokka:dokka-gradle-plugin:$dokka_version"
     }
 }
 
@@ -16,6 +19,7 @@ plugins {
 }
 
 apply plugin: 'kotlin'
+apply plugin: 'org.jetbrains.dokka'
 
 group 'com.adamratzman'
 version '2.1.0'
@@ -52,14 +56,28 @@ dependencies {
 
 }
 
+dokka {
+    outputFormat = 'gfm'
+    outputDirectory = 'docs/md'
+
+    jdkVersion = 8
+    includeNonPublic = false
+    impliedPlatforms = ["JVM"]
+
+    linkMapping {
+        dir = "src/main/kotlin"
+        url = "https://github.com/adamint/spotify-web-api-kotlin/tree/master/src/main/kotlin"
+        suffix = "#L"
+    }
+}
+
 spotless {
     kotlin {
         ktlint()
         licenseHeader '/* Created by Adam Ratzman (2018) */'    // License header
     }
 }
 
-
 test {
     systemProperties project.properties.subMap(
             ["clientId", "clientSecret", "spotifyTokenString", "spotifyRedirectUri"]

src/main/kotlin/com/adamratzman/spotify/endpoints/client/ClientFollowingAPI.kt

@@ -11,7 +11,6 @@ import com.adamratzman.spotify.utils.ArtistURI
 import com.adamratzman.spotify.utils.CursorBasedPagingObject
 import com.adamratzman.spotify.utils.EndpointBuilder
 import com.adamratzman.spotify.utils.PlaylistURI
-import com.adamratzman.spotify.utils.SpotifyPublicUser
 import com.adamratzman.spotify.utils.UserURI
 import com.adamratzman.spotify.utils.encode
 import com.adamratzman.spotify.utils.toArray
@@ -25,9 +24,9 @@ class ClientFollowingAPI(api: SpotifyAPI) : FollowingAPI(api) {
     /**
      * Check to see if the current user is following another Spotify users.
      *
-     * @param user Spotify ID to check.
+     * @param user user id or uri to check.
      *
-     * @throws BadRequestException if [userId] is a non-existing id
+     * @throws BadRequestException if [user] is a non-existing id
      */
     fun isFollowingUser(user: String): SpotifyRestAction<Boolean> {
         return toAction(Supplier {
@@ -38,8 +37,8 @@ class ClientFollowingAPI(api: SpotifyAPI) : FollowingAPI(api) {
     /**
      * Check to see if the logged-in Spotify user is following the specified playlist.
      *
-     * @param playlistOwner Spotify ID of the creator of the playlist
-     * @param playlistId Spotify playlist ID
+     * @param playlistOwner id or uri of the creator of the playlist
+     * @param playlistId playlist id or uri
      *
      * @return booleans representing whether the user follows the playlist. User IDs **not** found will return false
      *
@@ -60,7 +59,7 @@ class ClientFollowingAPI(api: SpotifyAPI) : FollowingAPI(api) {
      *
      * @param users List of the user Spotify IDs to check. Max 50
      *
-     * @throws BadRequestException if [userIds] contains a non-existing id
+     * @throws BadRequestException if [users] contains a non-existing id
      */
     fun isFollowingUsers(vararg users: String): SpotifyRestAction<List<Boolean>> {
         return toAction(Supplier {
@@ -74,9 +73,9 @@ class ClientFollowingAPI(api: SpotifyAPI) : FollowingAPI(api) {
     /**
      * Check to see if the current user is following a Spotify artist.
      *
-     * @param artistId Spotify ID to check.
+     * @param artist artist id to check.
      *
-     * @throws BadRequestException if [artistId] is a non-existing id
+     * @throws BadRequestException if [artist] is a non-existing id
      */
     fun isFollowingArtist(artist: String): SpotifyRestAction<Boolean> {
         return toAction(Supplier {
@@ -87,9 +86,9 @@ class ClientFollowingAPI(api: SpotifyAPI) : FollowingAPI(api) {
     /**
      * Check to see if the current user is following one or more artists.
      *
-     * @param artistIds List of the artist Spotify IDs to check. Max 50
+     * @param artists List of the artist ids or uris to check. Max 50
      *
-     * @throws BadRequestException if [artistIds] contains a non-existing id
+     * @throws BadRequestException if [artists] contains a non-existing id
      */
     fun isFollowingArtists(vararg artists: String): SpotifyRestAction<List<Boolean>> {
         return toAction(Supplier {
@@ -120,9 +119,6 @@ class ClientFollowingAPI(api: SpotifyAPI) : FollowingAPI(api) {
         })
     }
 
-    fun getFollowedUsers(): SpotifyRestAction<List<SpotifyPublicUser>> =
-        throw NotImplementedError("Though Spotify will implement this in the future, it is not currently supported.")
-
     /**
      * Add the current user as a follower of another user
      *
@@ -178,7 +174,7 @@ class ClientFollowingAPI(api: SpotifyAPI) : FollowingAPI(api) {
     /**
      * Add the current user as a follower of a playlist.
      *
-     * @param playlist The Spotify ID of the playlist. Any playlist can be followed, regardless of its
+     * @param playlist the spotify id or uri of the playlist. Any playlist can be followed, regardless of its
      * public/private status, as long as you know its playlist ID.
      * @param followPublicly Defaults to true. If true the playlist will be included in user’s public playlists,
      * if false it will remain private. To be able to follow playlists privately, the user must have granted the playlist-modify-private scope.
@@ -200,7 +196,7 @@ class ClientFollowingAPI(api: SpotifyAPI) : FollowingAPI(api) {
      *
      * @param user The user to be unfollowed from
      *
-     * @throws BadRequestException if [userId] is not found
+     * @throws BadRequestException if [user] is not found
      */
     fun unfollowUser(user: String): SpotifyRestAction<Unit> {
         return toAction(Supplier {
@@ -228,7 +224,7 @@ class ClientFollowingAPI(api: SpotifyAPI) : FollowingAPI(api) {
     /**
      * Remove the current user as a follower of an artist
      *
-     * @param artistId The artist to be unfollowed from
+     * @param artist The artist to be unfollowed from
      *
      * @throws BadRequestException if an invalid id is provided
      */
@@ -241,7 +237,7 @@ class ClientFollowingAPI(api: SpotifyAPI) : FollowingAPI(api) {
     /**
      * Remove the current user as a follower of artists
      *
-     * @param artistIds The artists to be unfollowed from
+     * @param artists The artists to be unfollowed from
      *
      * @throws BadRequestException if an invalid id is provided
      */
@@ -258,7 +254,7 @@ class ClientFollowingAPI(api: SpotifyAPI) : FollowingAPI(api) {
     /**
      * Remove the current user as a follower of a playlist.
      *
-     * @param playlistId The Spotify ID of the playlist that is to be no longer followed.
+     * @param playlist the spotify id or uri of the playlist that is to be no longer followed.
      *
      * @throws BadRequestException if the playlist is not found
      */

src/main/kotlin/com/adamratzman/spotify/endpoints/client/ClientLibraryAPI.kt

@@ -24,6 +24,11 @@ class ClientLibraryAPI(api: SpotifyAPI) : SpotifyEndpoint(api) {
     /**
      * Get a list of the songs saved in the current Spotify user’s ‘Your Music’ library.
      *
+     * @param limit The number of objects to return. Default: 20. Minimum: 1. Maximum: 50.
+     * @param offset The index of the first item to return. Default: 0. Use with limit to get the next set of items
+     * @param market Provide this parameter if you want the list of returned items to be relevant to a particular country.
+     * If omitted, the returned items will be relevant to all countries.
+     *
      * @return Paging Object of [SavedTrack] ordered by position in library
      */
     fun getSavedTracks(
@@ -42,6 +47,11 @@ class ClientLibraryAPI(api: SpotifyAPI) : SpotifyEndpoint(api) {
     /**
      * Get a list of the albums saved in the current Spotify user’s ‘Your Music’ library.
      *
+     * @param limit The number of objects to return. Default: 20. Minimum: 1. Maximum: 50.
+     * @param offset The index of the first item to return. Default: 0. Use with limit to get the next set of items
+     * @param market Provide this parameter if you want the list of returned items to be relevant to a particular country.
+     * If omitted, the returned items will be relevant to all countries.
+     *
      * @return Paging Object of [SavedAlbum] ordered by position in library
      */
     fun getSavedAlbums(
@@ -60,7 +70,10 @@ class ClientLibraryAPI(api: SpotifyAPI) : SpotifyEndpoint(api) {
     /**
      * Check if the [LibraryType] with id [id] is already saved in the current Spotify user’s ‘Your Music’ library.
      *
-     * @throws BadRequestException if [track] is not found
+     * @param type the type of object (album or track)
+     * @param id the spotify id or uri of the object
+     *
+     * @throws BadRequestException if [id] is not found
      */
     fun contains(type: LibraryType, id: String): SpotifyRestAction<Boolean> {
         return toAction(Supplier {
@@ -71,6 +84,9 @@ class ClientLibraryAPI(api: SpotifyAPI) : SpotifyEndpoint(api) {
     /**
      * Check if one or more of [LibraryType] is already saved in the current Spotify user’s ‘Your Music’ library.
      *
+     * @param type the type of objects (album or track)
+     * @param ids the spotify ids or uris of the objects
+     *
      * @throws BadRequestException if any of the provided ids is invalid
      */
     fun contains(type: LibraryType, vararg ids: String): SpotifyRestAction<List<Boolean>> {
@@ -85,6 +101,9 @@ class ClientLibraryAPI(api: SpotifyAPI) : SpotifyEndpoint(api) {
     /**
      * Save one of [LibraryType] to the current user’s ‘Your Music’ library.
      *
+     * @param type the type of object (album or track)
+     * @param id the spotify id or uri of the object
+     *
      * @throws BadRequestException if the id is invalid
      */
     fun add(type: LibraryType, id: String): SpotifyRestAction<Unit> {
@@ -96,6 +115,9 @@ class ClientLibraryAPI(api: SpotifyAPI) : SpotifyEndpoint(api) {
     /**
      * Save one or more of [LibraryType] to the current user’s ‘Your Music’ library.
      *
+     * @param type the type of objects to check against (album or track)
+     * @param ids the spotify ids or uris of the objects
+     *
      * @throws BadRequestException if any of the provided ids is invalid
      */
     fun add(type: LibraryType, vararg ids: String): SpotifyRestAction<Unit> {
@@ -108,6 +130,9 @@ class ClientLibraryAPI(api: SpotifyAPI) : SpotifyEndpoint(api) {
     /**
      * Remove one of [LibraryType] (track or album) from the current user’s ‘Your Music’ library.
      *
+     * @param type the type of object to check against (album or track)
+     * @param id the spotify id or uri of the object
+     *
      * @throws BadRequestException if any of the provided ids is invalid
      */
     fun remove(type: LibraryType, id: String): SpotifyRestAction<Unit> {
@@ -119,6 +144,9 @@ class ClientLibraryAPI(api: SpotifyAPI) : SpotifyEndpoint(api) {
     /**
      * Remove one or more of the [LibraryType] (tracks or albums) from the current user’s ‘Your Music’ library.
      *
+     * @param type the type of objects to check against (album or track)
+     * @param ids the spotify ids or uris of the objects
+     *
      * @throws BadRequestException if any of the provided ids is invalid
      */
     fun remove(type: LibraryType, vararg ids: String): SpotifyRestAction<Unit> {
@@ -129,6 +157,12 @@ class ClientLibraryAPI(api: SpotifyAPI) : SpotifyEndpoint(api) {
     }
 }
 
+/**
+ * Type of object in a user's Spotify library
+ *
+ * @param value Spotify id for the type
+ * @param id how to transform an id (or uri) input into its Spotify id
+ */
 enum class LibraryType(private val value: String, internal val id: (String) -> String) {
     TRACK("tracks", { TrackURI(it).id }), ALBUM("albums", { AlbumURI(it).id });
 

src/main/kotlin/com/adamratzman/spotify/endpoints/client/ClientPersonalizationAPI.kt

@@ -15,6 +15,11 @@ import java.util.function.Supplier
  * Endpoints for retrieving information about the user’s listening habits.
  */
 class ClientPersonalizationAPI(api: SpotifyAPI) : SpotifyEndpoint(api) {
+    /**
+     * The time frame for which attribute affinities are computed.
+     *
+     * @param id the Spotify id of the time frame
+     */
     enum class TimeRange(val id: String) {
         LONG_TERM("long_term"), MEDIUM_TERM("medium_term"), SHORT_TERM("short_term");
 
@@ -31,6 +36,10 @@ class ClientPersonalizationAPI(api: SpotifyAPI) : SpotifyEndpoint(api) {
      * for each user. In the future, it is likely that this restriction will be relaxed. This data is typically updated
      * once each day for each user.
      *
+     * @param limit The number of objects to return. Default: 20. Minimum: 1. Maximum: 50.
+     * @param offset The index of the first item to return. Default: 0. Use with limit to get the next set of items
+     * @param timeRange the time range to which to compute this. The default is [TimeRange.MEDIUM_TERM]
+     *
      * @return [PagingObject] of full [Artist] objects sorted by affinity
      */
     fun getTopArtists(
@@ -57,6 +66,10 @@ class ClientPersonalizationAPI(api: SpotifyAPI) : SpotifyEndpoint(api) {
      * for each user. In the future, it is likely that this restriction will be relaxed. This data is typically updated
      * once each day for each user.
      *
+     * @param limit The number of objects to return. Default: 20. Minimum: 1. Maximum: 50.
+     * @param offset The index of the first item to return. Default: 0. Use with limit to get the next set of items
+     * @param timeRange the time range to which to compute this. The default is [TimeRange.MEDIUM_TERM]
+     *
      * @return [PagingObject] of full [Track] objects sorted by affinity
      */
     fun getTopTracks(