fix existing documentation errors

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

Author: adamint

build.gradle

@@ -19,7 +19,7 @@ plugins {
 }
 
 apply plugin: 'kotlin'
-apply plugin: 'org.jeaddtbrains.dokka'
+apply plugin: 'org.jetbrains.dokka'
 
 group 'com.adamratzman'
 version '2.1.0'

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

@@ -24,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 {
@@ -37,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
      *
@@ -59,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 {
@@ -73,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 {
@@ -86,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 {
@@ -174,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.
@@ -196,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 {
@@ -224,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
      */
@@ -237,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
      */
@@ -254,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(

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

@@ -127,20 +127,20 @@ class ClientPlayerAPI(api: SpotifyAPI) : SpotifyEndpoint(api) {
 
     /**
      * Start or resume playback.
-     * **Note:** Only one of the following can be used: [albumId], [artistId], [playlist], or [tracksToPlay]. Else, you will
+     * **Note:** Only one of the following can be used: [album], [artist], [playlist], or [tracksToPlay]. Else, you will
      * not see expected results.
      *
      * **Note also:** You can only use one of the following: [offsetNum] or [offsetTrackId]
      *
      * **Specify nothing to play to simply resume playback**
      *
-     * @param albumId an album id to play
-     * @param artistId an artist id for whom to play
-     * @param playlist a playlist id from which to play
-     * @param tracksToPlay track ids to play. these are converted into URIs. Max 100
-     * @param offsetNum Indicates from where in the context playback should start. Only available with use of [albumId] or [playlist]
+     * @param album an album id or uri to play
+     * @param artist an artist id or uri for whom to play
+     * @param playlist a playlist id or uri from which to play
+     * @param tracksToPlay track ids or uris to play. these are converted into URIs. Max 100
+     * @param offsetNum Indicates from where in the context playback should start. Only available with use of [album] or [playlist]
      * or when [tracksToPlay] is used.
-     * @param offsetTrackId Does the same as [offsetNum] but with a track id instead of place number
+     * @param offsetTrackId Does the same as [offsetNum] but with a track id or uri instead of place number
      * @param deviceId the device to play on
      *
      * @throws BadRequestException if more than one type of play type is specified or the offset is illegal.