update documentation to reflect current online docs

Author: adamint

src/main/kotlin/com/adamratzman/spotify/SpotifyAPI.kt

@@ -110,6 +110,8 @@ class SpotifyAppAPI internal constructor(clientId: String, clientSecret: String,
             tracks,
             following
     )
+
+    override fun equals(other: Any?) = other is SpotifyAppAPI && other.token == this.token
 }
 
 class SpotifyClientAPI internal constructor(
@@ -202,6 +204,8 @@ class SpotifyClientAPI internal constructor(
     fun getAuthorizationUrl(vararg scopes: SpotifyScope): String {
         return getAuthUrlFull(*scopes, clientId = clientId, redirectUri = redirectUri)
     }
+
+    override fun equals(other: Any?) = other is SpotifyClientAPI && other.token == this.token
 }
 
 internal fun getAuthUrlFull(vararg scopes: SpotifyScope, clientId: String, redirectUri: String): String {

src/main/kotlin/com/adamratzman/spotify/SpotifyLogger.kt

@@ -4,9 +4,11 @@ package com.adamratzman.spotify
 class SpotifyLogger(var enabled: Boolean) {
     val redString = "\u001B[31m"
     val resetString = "\u001B[0m"
+
     fun logInfo(message: String) {
         if (enabled) println("Spotify Logger Info: $message")
     }
+
     fun logWarning(message: String) {
         if (enabled) println("${redString}Spotify Logger Warning: $message$resetString")
     }

src/main/kotlin/com/adamratzman/spotify/SpotifyRestAction.kt

@@ -6,7 +6,14 @@ import java.util.concurrent.CompletableFuture
 import java.util.concurrent.TimeUnit
 import java.util.function.Supplier
 
-open class SpotifyRestAction<T>(protected val api: SpotifyAPI, private val supplier: Supplier<T>) {
+/**
+ * Provides a uniform interface to retrieve, whether synchronously or asynchronously, [T] from Spotify
+ */
+open class SpotifyRestAction<T> internal constructor(protected val api: SpotifyAPI, private val supplier: Supplier<T>) {
+
+    /**
+     * Invoke [supplier] and synchronously retrieve [T]
+     */
     fun complete(): T {
         return try {
             supplier.get()
@@ -15,10 +22,24 @@ open class SpotifyRestAction<T>(protected val api: SpotifyAPI, private val suppl
         }
     }
 
+    /**
+     * Invoke [supplier] asynchronously with no consumer
+     */
     fun queue() = queue({}, { throw it })
 
+    /**
+     * Invoke [supplier] asynchronously and consume [consumer] with the [T] value returned
+     *
+     * @param consumer to be invoked with [T] after successful completion of [supplier]
+     */
     fun queue(consumer: (T) -> Unit) = queue(consumer, {})
 
+    /**
+     * Invoke [supplier] asynchronously and consume [consumer] with the [T] value returned
+     *
+     * @param failure Consumer to invoke when an exception is thrown by [supplier]
+     * @param consumer to be invoked with [T] after successful completion of [supplier]
+     */
     fun queue(consumer: ((T) -> Unit), failure: ((Throwable) -> Unit)) {
         api.executor.execute {
             try {
@@ -30,8 +51,18 @@ open class SpotifyRestAction<T>(protected val api: SpotifyAPI, private val suppl
         }
     }
 
+    /**
+     * Return [supplier] as a [CompletableFuture]
+     */
     fun asFuture() = CompletableFuture.supplyAsync(supplier)
 
+    /**
+     * Invoke [supplier] asynchronously immediately and invoke [consumer] after the specified quantity of time
+     *
+     * @param quantity amount of time
+     * @param timeUnit the unit that [quantity] is in
+     * @param consumer to be invoked with [T] after successful completion of [supplier]
+     */
     fun queueAfter(quantity: Int, timeUnit: TimeUnit = TimeUnit.SECONDS, consumer: (T) -> Unit) {
         val runAt = System.currentTimeMillis() + timeUnit.toMillis(quantity.toLong())
         queue { result ->
@@ -43,7 +74,26 @@ open class SpotifyRestAction<T>(protected val api: SpotifyAPI, private val suppl
 }
 
 class SpotifyRestActionPaging<Z, T : AbstractPagingObject<Z>>(api: SpotifyAPI, supplier: Supplier<T>) :
-    SpotifyRestAction<T>(api, supplier) {
+        SpotifyRestAction<T>(api, supplier) {
+
+    /**
+     * Synchronously retrieve all [AbstractPagingObject] associated with this rest action
+     */
     fun getAll() = api.tracks.toAction(Supplier { complete().getAllImpl() })
+
+    /**
+     * Synchronously retrieve all [Z] associated with this rest action
+     */
     fun getAllItems() = api.tracks.toAction(Supplier { complete().getAllImpl().toList().map { it.items }.flatten() })
+
+    /**
+     * Consume each [Z] by [consumer] as it is retrieved
+     */
+    fun streamAllItems(consumer: (Z) -> Unit): SpotifyRestAction<Unit> {
+        return api.tracks.toAction(
+                Supplier {
+                    complete().getAllImpl().toList().forEach { it.items.forEach { item -> consumer(item) } }
+                }
+        )
+    }
 }

src/main/kotlin/com/adamratzman/spotify/SpotifyScope.kt

@@ -1,6 +1,15 @@
 /* Spotify Web API - Kotlin Wrapper; MIT License, 2019; Original author: Adam Ratzman */
 package com.adamratzman.spotify
 
+/**
+ * Scopes provide Spotify users using third-party apps the confidence
+ * that only the information they choose to share will be shared, and nothing more.
+ *
+ * Each represents a distinct privilege and may be required by one or more endpoints as discussed
+ * on the [Spotify Authorization Documentation](https://developer.spotify.com/documentation/general/guides/scopes/)
+ *
+ * @property uri the scope id
+ */
 enum class SpotifyScope(val uri: String) {
     PLAYLIST_READ_PRIVATE("playlist-read-private"),
     PLAYLIST_READ_COLLABORATIVE("playlist-read-collaborative"),

src/main/kotlin/com/adamratzman/spotify/models/Albums.kt

@@ -1,9 +1,12 @@
 /* Spotify Web API - Kotlin Wrapper; MIT License, 2019; Original author: Adam Ratzman */
 package com.adamratzman.spotify.models
 
+import com.adamratzman.spotify.utils.match
 import com.beust.klaxon.Json
 
 /**
+ * Simplified Album object that can be used to retrieve a full [Album]
+ *
  * @property albumGroup Optional. The field is present when getting an artist’s albums. Possible values
  * are “album”, “single”, “compilation”, “appears_on”. Compare to album_type this field represents relationship
  * between the artist and the album.
@@ -36,27 +39,35 @@ data class SimpleAlbum(
     val images: List<SpotifyImage>,
     val name: String,
     val type: String,
+    val restrictions: Restrictions? = null,
     @Json(name = "uri", ignored = false) private val _uri: String,
-    @Json(ignored = true) val uri: AlbumURI = AlbumURI(_uri),
     @Json(name = "release_date") val releaseDate: String,
     @Json(name = "release_date_precision") val releaseDatePrecision: String,
     @Json(name = "total_tracks") val totalTracks: Int? = null,
-    @Json(name = "album_group", ignored = false) private val albumGroupString: String? = null,
-    val restrictions: Restrictions? = null,
-    @Json(ignored = true) val albumGroup: AlbumResultType? = albumGroupString?.let { _ ->
-        AlbumResultType.values().find { it.id == albumGroupString }
-    }
+    @Json(name = "album_group", ignored = false) private val albumGroupString: String? = null
 ) : Linkable() {
+    @Json(ignored = true) val uri: AlbumURI = AlbumURI(_uri)
+
     @Json(ignored = true)
     val albumType: AlbumResultType = _albumType.let { _ ->
         AlbumResultType.values().first { it.id.equals(_albumType, true) }
     }
 
+    @Json(ignored = true) val albumGroup: AlbumResultType? = albumGroupString?.let { _ ->
+        AlbumResultType.values().find { it.id == albumGroupString }
+    }
+
+    /**
+     * Converts this [SimpleAlbum] into a full [Album] object with the given
+     * market
+     *
+     * @param market Provide this parameter if you want the list of returned items to be relevant to a particular country.
+     */
     fun toFullAlbum(market: Market? = null) = api.albums.getAlbum(id, market)
 }
 
 /**
- * Album type
+ * Album search type
  */
 enum class AlbumResultType(internal val id: String) {
     ALBUM("album"),
@@ -66,6 +77,8 @@ enum class AlbumResultType(internal val id: String) {
 }
 
 /**
+ * Represents an Album on Spotify
+ *
  * @property albumType The type of the album: one of "album" , "single" , or "compilation".
  * @property artists The artists of the album. Each artist object includes a link in href to more detailed
  * information about the artist.
@@ -115,22 +128,41 @@ data class Album(
     val tracks: PagingObject<SimpleTrack>,
     val type: String,
     @Json(name = "uri", ignored = false) private val _uri: String,
-    @Json(ignored = true) val uri: AlbumURI = AlbumURI(_uri),
     @Json(name = "total_tracks") val totalTracks: Int,
-    val restrictions: Restrictions? = null,
+    val restrictions: Restrictions? = null
+) {
+    @Json(ignored = true) val uri: AlbumURI = AlbumURI(_uri)
+
     @Json(ignored = true) val albumType: AlbumResultType = AlbumResultType.values().first { it.id == _albumType }
-)
+}
 
 /**
- * Describes an album's copyright
+ * Describes an album's copyright information
  *
  * @property text The copyright text for this album.
  * @property type The type of copyright: C = the copyright,
  * P = the sound recording (performance) copyright.
  */
 data class SpotifyCopyright(
-    val text: String,
-    val type: String
-)
+        @Json(name="text") private val _text: String,
+        @Json(name="type") private val _type: String
+) {
+    @Json(ignored = true) val text = _text
+            .removePrefix("(P)")
+            .removePrefix("(C)")
+            .trim()
+    @Json(ignored = true) val type = CopyrightType.values().match(_type)!!
+}
+
+internal data class AlbumsResponse(val albums: List<Album?>)
+
+/**
+ * Copyright statement type of an Album
+ */
+enum class CopyrightType(val identifier: String): ResultEnum {
+    COPYRIGHT("C"),
+    SOUND_PERFORMANCE_COPYRIGHT("P")
+    ;
 
-internal data class AlbumsResponse(val albums: List<Album?>)
+    override fun retrieveIdentifier() = identifier
+}

src/main/kotlin/com/adamratzman/spotify/models/Artists.kt

@@ -4,6 +4,8 @@ package com.adamratzman.spotify.models
 import com.beust.klaxon.Json
 
 /**
+ * Simplified Artist object that can be used to retrieve a full [Artist]
+ *
  * @property externalUrls Known external URLs for this artist.
  * @property href A link to the Web API endpoint providing full details of the artist.
  * @property id The Spotify ID for the artist.
@@ -17,13 +19,19 @@ data class SimpleArtist(
     val id: String,
     val name: String,
     val type: String,
-    @Json(name = "uri", ignored = false) private val _uri: String,
-    @Json(ignored = true) val uri: ArtistURI = ArtistURI(_uri)
+    @Json(name = "uri", ignored = false) private val _uri: String
 ) : Linkable() {
+    @Json(ignored = true) val uri: ArtistURI = ArtistURI(_uri)
+
+    /**
+     * Converts this [SimpleArtist] into a full [Artist] object
+     */
     fun toFullArtist() = api.artists.getArtist(id)
 }
 
 /**
+ * Represents an Artist (distinct from a regular user) on Spotify
+ *
  * @property externalUrls Known external URLs for this artist.
  * @property followers Information about the followers of the artist.
  * @property genres A list of the genres the artist is associated with. For example: "Prog Rock" ,
@@ -47,8 +55,9 @@ data class Artist(
     val name: String,
     val popularity: Int,
     val type: String,
-    @Json(name = "uri", ignored = false) private val _uri: String,
+    @Json(name = "uri", ignored = false) private val _uri: String
+) {
     @Json(ignored = true) val uri: ArtistURI = ArtistURI(_uri)
-)
+}
 
 internal data class ArtistList(val artists: List<Artist?>)

src/main/kotlin/com/adamratzman/spotify/models/Authentication.kt

@@ -5,15 +5,24 @@ import com.adamratzman.spotify.SpotifyScope
 import com.beust.klaxon.Json
 
 /**
- * Represents a Spotify Token, retrieved through instantiating a new [SpotifyAPI]
+ * Represents a Spotify Token, retrieved through instantiating a [SpotifyAPI]
+ *
+ * @property accessToken An access token that can be provided in subsequent calls,
+ * for example to Spotify Web API services.
+ * @property tokenType How the access token may be used: always “Bearer”.
+ * @property expiresIn The time period (in seconds) for which the access token is valid.
+ * @property refreshToken A token that can be sent to the Spotify Accounts service in place of an authorization code,
+ * null if the token was created using a method that does not support token refresh
+ * @property scopes A list of scopes granted access for this [accessToken]. An
+ * empty list means that the token can only be used to acces public information.
  */
 data class Token(
-    @Json(name = "access_token") val accessToken: String,
-    @Json(name = "token_type") val tokenType: String,
-    @Json(name = "expires_in")val expiresIn: Int,
-    @Json(name = "refresh_token") val refreshToken: String? = null,
-    @Json(ignored = false) private val scopeString: String? = null,
-    @Json(ignored = true) val scopes: List<SpotifyScope>? = scopeString?.let { str ->
-        str.split(" ").mapNotNull { scope -> SpotifyScope.values().find { it.uri == scope } }
-    }
+        @Json(name = "access_token") val accessToken: String,
+        @Json(name = "token_type") val tokenType: String,
+        @Json(name = "expires_in") val expiresIn: Int,
+        @Json(name = "refresh_token") val refreshToken: String? = null,
+        @Json(ignored = false) private val scopeString: String? = null,
+        @Json(ignored = true) val scopes: List<SpotifyScope> = scopeString?.let { str ->
+            str.split(" ").mapNotNull { scope -> SpotifyScope.values().find { it.uri.equals(scope, true) } }
+        } ?: listOf()
 )

src/main/kotlin/com/adamratzman/spotify/models/Browse.kt

@@ -10,10 +10,10 @@ package com.adamratzman.spotify.models
  * @property name The name of the category.
  */
 data class SpotifyCategory(
-    val href: String,
-    val icons: List<SpotifyImage>,
-    val id: String,
-    val name: String
+        val href: String,
+        val icons: List<SpotifyImage>,
+        val id: String,
+        val name: String
 )
 
 /**
@@ -29,12 +29,12 @@ data class SpotifyCategory(
  * @property type The entity type of this seed. One of artist , track or genre.
  */
 data class RecommendationSeed(
-    val initialPoolSize: Int,
-    val afterFilteringSize: Int,
-    val afterRelinkingSize: Int?,
-    val href: String?,
-    val id: String,
-    val type: String
+        val initialPoolSize: Int,
+        val afterFilteringSize: Int,
+        val afterRelinkingSize: Int?,
+        val href: String?,
+        val id: String,
+        val type: String
 )
 
 /**

src/main/kotlin/com/adamratzman/spotify/models/Library.kt

@@ -4,15 +4,19 @@ package com.adamratzman.spotify.models
 import com.beust.klaxon.Json
 
 /**
+ * Represents an album saved in a user's library
+ *
  * @property addedAt The date and time the album was saved.
- * @property track Information about the album.
+ * @property album Information about the album.
  */
 data class SavedAlbum(
     @Json(name = "added_at") val addedAt: String,
     val album: Album
 )
 
 /**
+ * Represents a track saved in a user's library
+ *
  * @property addedAt The date and time the track was saved.
  * @property track The track object.
  */

src/main/kotlin/com/adamratzman/spotify/models/Market.kt

@@ -4,7 +4,7 @@ package com.adamratzman.spotify.models
 /**
  * Represents Spotify markets (countries + distinctive territories)
  *
- * @param country the readable country/territory name of the market
+ * @property country the readable country/territory name of the market
  */
 enum class Market(val country: String) {
     AD("Andorra"),