Merge remote-tracking branch 'origin/1.5.0' into 1.5.0

Author: Gruncan

src/main/java/dev/gruncan/spotify/objects/episodes/EpisodePage.java

@@ -3,11 +3,23 @@
 import dev.gruncan.spotify.objects.SpotifyField;
 import dev.gruncan.spotify.objects.SpotifyObject;
 import dev.gruncan.spotify.objects.search.AbstractSearchItems;
+import dev.gruncan.spotify.requests.me.episodes.MyEpisodesGet;
 import lombok.Getter;
 
+/**
+ * Represents a page of episodes
+ *
+ * @see MyEpisodesGet
+ * @see SavedEpisode
+ * @see AbstractSearchItems
+ * @see SpotifyObject
+ */
 @Getter
 public class EpisodePage extends AbstractSearchItems implements SpotifyObject {
 
+    /**
+     * An array of SavedEpisodes
+     */
     @SpotifyField
     private SavedEpisode[] items;
 

src/main/java/dev/gruncan/spotify/objects/episodes/SavedEpisode.java

@@ -4,13 +4,25 @@
 import dev.gruncan.spotify.objects.SpotifyObject;
 import lombok.Getter;
 
+/**
+ * Represents a saved episode
+ *
+ * @see EpisodePage
+ * @see Episode
+ * @see SpotifyObject
+ */
 @Getter
 public class SavedEpisode implements SpotifyObject {
 
-
+    /**
+     * The date and time the episode was saved. Timestamps are returned in ISO 8601 format as Coordinated Universal Time (UTC) with a zero offset: YYYY-MM-DDTHH:MM:SSZ.
+     */
     @SpotifyField("added_at")
     private String addedAt;
 
+    /**
+     * Information about the episode.
+     */
     @SpotifyField
     private Episode episode;
 

src/main/java/dev/gruncan/spotify/objects/player/PlayTrackHistory.java

@@ -3,18 +3,36 @@
 import dev.gruncan.spotify.objects.SpotifyField;
 import dev.gruncan.spotify.objects.SpotifyObject;
 import dev.gruncan.spotify.objects.tracks.Track;
+import dev.gruncan.spotify.objects.tracks.TrackPage;
 import lombok.Getter;
 
+
+/**
+ * Represents a history of a track that was played
+ *
+ * @see TrackPage
+ * @see Track
+ * @see PlayerContext
+ * @see SpotifyObject
+ */
 @Getter
 public class PlayTrackHistory implements SpotifyObject {
 
-
+    /**
+     * The track the user listened to.
+     */
     @SpotifyField
     private Track track;
 
+    /**
+     * The date and time the track was played.
+     */
     @SpotifyField("played_at")
     private String playedAt;
 
+    /**
+     * The context the track was played from.
+     */
     @SpotifyField
     private PlayerContext context;
 

src/main/java/dev/gruncan/spotify/objects/player/PlaybackState.java

@@ -5,41 +5,85 @@
 import dev.gruncan.spotify.objects.SpotifyOptional;
 import dev.gruncan.spotify.objects.episodes.Episode;
 import dev.gruncan.spotify.objects.tracks.Track;
+import dev.gruncan.spotify.requests.me.player.MyPlayerCurrentlyPlayingGet;
+import dev.gruncan.spotify.requests.me.player.MyPlayerGet;
 import lombok.Getter;
 
+/**
+ * Represents information about playback
+ *
+ * @see MyPlayerGet
+ * @see MyPlayerCurrentlyPlayingGet
+ * @see SpotifyDevice
+ * @see PlayerContext
+ * @see Track
+ * @see Episode
+ * @see PlayerActions
+ * @see SpotifyObject
+ */
 @Getter
 public class PlaybackState implements SpotifyObject {
 
+    /**
+     * The device that is currently active.
+     */
     @SpotifyField
     private SpotifyDevice device;
 
+    /**
+     * off, track, context
+     */
     @SpotifyField("repeat_state")
     private String repeatState;
 
+    /**
+     * If shuffle is on or off.
+     */
     @SpotifyField("shuffle_state")
     private boolean isShuffled;
 
+    /**
+     * A Context Object. Can be null.
+     */
     @SpotifyOptional
     @SpotifyField
     private PlayerContext context;
 
+    /**
+     * Unix Millisecond Timestamp when data was fetched.
+     */
     @SpotifyField
     private int timestamp;
 
+    /**
+     * Progress into the currently playing track or episode. Can be null.
+     */
     @SpotifyField("progress_ms")
     private int progress;
 
+    /**
+     * The currently playing track if present
+     */
     @SpotifyOptional
-    @SpotifyField("item")
+    @SpotifyField(value = "item", canSkip = true)
     private Track track;
 
+    /**
+     * The currently playing episode if present
+     */
     @SpotifyOptional
-    @SpotifyField("item")
+    @SpotifyField(value = "item", canSkip = true)
     private Episode episode;
 
+    /**
+     * The object type of the currently playing item. Can be one of track, episode, ad or unknown.
+     */
     @SpotifyField("currently_playing_type")
     private String currentlyPlayingType;
 
+    /**
+     * Allows to update the user interface based on which playback actions are available within the current context.
+     */
     @SpotifyField
     private PlayerActions actions;
 

src/main/java/dev/gruncan/spotify/objects/player/PlayerActions.java

@@ -2,39 +2,76 @@
 
 import dev.gruncan.spotify.objects.SpotifyField;
 import dev.gruncan.spotify.objects.SpotifyObject;
+import dev.gruncan.spotify.objects.SpotifyOptional;
 import lombok.Getter;
 
+/**
+ * Represents the action available within the current context
+ *
+ * @see PlaybackState
+ * @see SpotifyObject
+ */
 @Getter
+@SpotifyOptional
 public class PlayerActions implements SpotifyObject {
 
-
+    /**
+     * Interrupting playback
+     */
     @SpotifyField("interrupting_playback")
     private boolean isInterruptingPlayback;
 
+    /**
+     * Pausing
+     */
     @SpotifyField("pausing")
     private boolean isPausing;
 
+    /**
+     * Resuming
+     */
     @SpotifyField("resuming")
     private boolean isResuming;
 
+    /**
+     * Seeking playback location
+     */
     @SpotifyField("seeking")
     private boolean isSeeking;
 
+    /**
+     * Skipping to the next context
+     */
     @SpotifyField("skipping_next")
     private boolean isSkippingNext;
 
+    /**
+     * Skipping to the previous context
+     */
     @SpotifyField("skipping_prev")
     private boolean isSkippingPrev;
 
+    /**
+     * Toggling repeat context flag
+     */
     @SpotifyField("toggling_repeat_context")
     private boolean isTogglingRepeatContext;
 
+    /**
+     * Toggling shuffle flag
+     */
     @SpotifyField("toggling_shuffle")
     private boolean isTogglingShuffle;
 
+    /**
+     * Toggling repeat track flag
+     */
     @SpotifyField("toggling_repeat_track")
     private boolean isTogglingRepeatTrack;
 
+    /**
+     * Transferring playback between devices
+     */
     @SpotifyField("transferring_playback")
     private boolean isTransferringPlayback;
 

src/main/java/dev/gruncan/spotify/objects/player/PlayerContext.java

@@ -4,19 +4,38 @@
 import dev.gruncan.spotify.objects.SpotifyObject;
 import lombok.Getter;
 
+/**
+ * Represents the current player context
+ *
+ * @see PlaybackState
+ * @see SpotifyObject
+ *
+ */
 @Getter
 public class PlayerContext implements SpotifyObject {
 
-
+    /**
+     * The object type, e.g. "artist", "playlist", "album", "show".
+     */
     @SpotifyField
     private String type;
 
+    /**
+     * A link to the Web API endpoint providing full details of the track.
+     */
     @SpotifyField
     private String href;
 
+    /**
+     * External URLs for this context.
+     * The Spotify URL for the object.
+     */
     @SpotifyField(value = "spotify", path = "external_urls")
     private String externalUrls;
 
+    /**
+     * The Spotify URI for the context.
+     */
     @SpotifyField
     private String uri;
 

src/main/java/dev/gruncan/spotify/objects/player/SpotifyDevice.java

@@ -5,28 +5,56 @@
 import dev.gruncan.spotify.objects.SpotifyOptional;
 import lombok.Getter;
 
+
+/**
+ * Represents a spotify device
+ *
+ * @see SpotifyDeviceArray
+ * @see SpotifyObject
+ */
 @Getter
 public class SpotifyDevice implements SpotifyObject {
 
+    /**
+     * The device ID.
+     */
     @SpotifyOptional
     @SpotifyField
     private String id;
 
+    /**
+     * If this device is the currently active device.
+     */
     @SpotifyField("is_active")
     private boolean isActive;
 
+    /**
+     * If this device is currently in a private session.
+     */
     @SpotifyField("is_private_session")
     private boolean isPrivateSession;
 
+    /**
+     * Whether controlling this device is restricted. At present if this is "true" then no Web API commands will be accepted by this device.
+     */
     @SpotifyField("is_restricted")
     private boolean isRestricted;
 
+    /**
+     * A human-readable name for the device. Some devices have a name that the user can configure (e.g. "Loudest speaker") and some devices have a generic name associated with the manufacturer or device model.
+     */
     @SpotifyField
     private String name;
 
+    /**
+     * Device type, such as "computer", "smartphone" or "speaker".
+     */
     @SpotifyField
     private String type;
 
+    /**
+     * The current volume in percent.
+     */
     @SpotifyOptional
     @SpotifyField("volume_percent")
     private int volume;

src/main/java/dev/gruncan/spotify/objects/player/SpotifyDeviceArray.java

@@ -2,12 +2,22 @@
 
 import dev.gruncan.spotify.objects.SpotifyField;
 import dev.gruncan.spotify.objects.SpotifyObject;
+import dev.gruncan.spotify.requests.me.player.MyPlayerDevicesGet;
 import lombok.Getter;
 
+/**
+ * Represents a set of devices
+ *
+ * @see MyPlayerDevicesGet
+ * @see SpotifyDevice
+ * @see SpotifyObject
+ */
 @Getter
 public class SpotifyDeviceArray implements SpotifyObject {
 
-
+    /**
+     * The set of spotify devices
+     */
     @SpotifyField
     private SpotifyDevice[] devices;
 

src/main/java/dev/gruncan/spotify/objects/playlists/Playlist.java

@@ -5,6 +5,7 @@
 import dev.gruncan.spotify.objects.search.items.SearchItemsPlaylists;
 import dev.gruncan.spotify.objects.wrappers.SpotifyFollowers;
 import dev.gruncan.spotify.requests.playlists.PlaylistGet;
+import dev.gruncan.spotify.requests.users.UserPlaylistCreatePost;
 import lombok.Getter;
 
 
@@ -13,7 +14,10 @@
  * Serialized from <a href="https://developer.spotify.com/documentation/web-api/reference/get-playlist">PlaylistGet</a>
  *
  * @see PlaylistGet
+ * @see UserPlaylistCreatePost
  * @see SearchItemsPlaylists
+ * @see SimplifiedPlaylist
+ * @see SpotifyFollowers
  * @see SpotifyObject
  */
 @Getter