From c829adde0b4b28b872a96f5c696160bafec1012f Mon Sep 17 00:00:00 2001
From: Jonas Dellinger <jonas@dellinger.dev>
Date: Sat, 6 Jun 2020 17:43:49 +0200
Subject: [PATCH] Added docs for IPlayableItem, fixes #454

---
 SpotifyAPI.Docs/docs/iplayableitem.md         | 39 +++++++++++++++++++
 SpotifyAPI.Docs/sidebars.js                   |  1 +
 .../Models/Response/CurrentlyPlaying.cs       |  4 ++
 .../Response/CurrentlyPlayingContext.cs       |  4 ++
 .../Models/Response/FullPlaylist.cs           |  5 +++
 .../Models/Response/SimplePlaylist.cs         |  5 +++
 6 files changed, 58 insertions(+)
 create mode 100644 SpotifyAPI.Docs/docs/iplayableitem.md

diff --git a/SpotifyAPI.Docs/docs/iplayableitem.md b/SpotifyAPI.Docs/docs/iplayableitem.md
new file mode 100644
index 00000000..8cfb9e68
--- /dev/null
+++ b/SpotifyAPI.Docs/docs/iplayableitem.md
@@ -0,0 +1,39 @@
+---
+id: iplayableitem
+title: IPlayableItem
+---
+
+When working with playlists or the current playing context, you will encounter a type `IPlayableItem`, which only contains a `Type` property. Spotify recently introduced shows/episodes to the API, and thus had to adapt API endpoints which previously just returned track objects. Now, playlists and the current playing context can include two types, tracks and episodes. To reflect this in our models, we introduced `IPlayableItem`.
+
+```csharp
+var spotify = new SpotifyClient("YourAccessToken");
+
+var playlist = await spotify.Playlists.Get("37i9dQZEVXbMDoHDwVN2tF");
+foreach (PlaylistTrack<IPlayableItem> item in playlist.Tracks.Items)
+{
+  // When was it added
+  Console.WriteLine(item.AddedAt);
+  // The only propety on item is item.Type, it's a IPlayableItem
+  Console.WriteLine(item.Track.Type);
+}
+```
+
+Now, this type per se is probably useless to you. You're interested in the name, uri or artist of the episode/track. To get that info, you have to type cast the `IPlayableItem` to the respective type:
+
+```csharp
+foreach (PlaylistTrack<IPlayableItem> item in playlist.Tracks.Items)
+{
+  if (item.Track is FullTrack track)
+  {
+    // All FullTrack properties are available
+    Console.WriteLine(track.Name);
+  }
+  if (item.Track is FullEpisode episode)
+  {
+    // All FullTrack properties are available
+    Console.WriteLine(episode.Name);
+  }
+}
+```
+
+To this day, `IPlayableItem` can only be `FullTrack` or `FullEpisode`.
diff --git a/SpotifyAPI.Docs/sidebars.js b/SpotifyAPI.Docs/sidebars.js
index cfff1e13..1eb3704f 100644
--- a/SpotifyAPI.Docs/sidebars.js
+++ b/SpotifyAPI.Docs/sidebars.js
@@ -13,6 +13,7 @@ module.exports = {
           'proxy',
           'pagination',
           'retry_handling',
+          'iplayableitem',
           'unit_testing'
         ]
       },
diff --git a/SpotifyAPI.Web/Models/Response/CurrentlyPlaying.cs b/SpotifyAPI.Web/Models/Response/CurrentlyPlaying.cs
index e4a82932..e39fd6ef 100644
--- a/SpotifyAPI.Web/Models/Response/CurrentlyPlaying.cs
+++ b/SpotifyAPI.Web/Models/Response/CurrentlyPlaying.cs
@@ -9,6 +9,10 @@ namespace SpotifyAPI.Web
     public string CurrentlyPlayingType { get; set; } = default!;
     public bool IsPlaying { get; set; }
 
+    /// <summary>
+    /// Can be a FullTrack or FullEpisode
+    /// </summary>
+    /// <value></value>
     [JsonConverter(typeof(PlayableItemConverter))]
     public IPlayableItem Item { get; set; } = default!;
     public int? ProgressMs { get; set; }
diff --git a/SpotifyAPI.Web/Models/Response/CurrentlyPlayingContext.cs b/SpotifyAPI.Web/Models/Response/CurrentlyPlayingContext.cs
index 8e3b389e..0ac9c4c1 100644
--- a/SpotifyAPI.Web/Models/Response/CurrentlyPlayingContext.cs
+++ b/SpotifyAPI.Web/Models/Response/CurrentlyPlayingContext.cs
@@ -12,6 +12,10 @@ namespace SpotifyAPI.Web
     public int ProgressMs { get; set; }
     public bool IsPlaying { get; set; }
 
+    /// <summary>
+    /// Can be a FullTrack or FullEpisode
+    /// </summary>
+    /// <value></value>
     [JsonConverter(typeof(PlayableItemConverter))]
     public IPlayableItem Item { get; set; } = default!;
 
diff --git a/SpotifyAPI.Web/Models/Response/FullPlaylist.cs b/SpotifyAPI.Web/Models/Response/FullPlaylist.cs
index 56c21169..fa6945b8 100644
--- a/SpotifyAPI.Web/Models/Response/FullPlaylist.cs
+++ b/SpotifyAPI.Web/Models/Response/FullPlaylist.cs
@@ -12,6 +12,11 @@ namespace SpotifyAPI.Web
     public PublicUser Owner { get; set; } = default!;
     public bool Public { get; set; }
     public string SnapshotId { get; set; } = default!;
+
+    /// <summary>
+    /// A list of PlaylistTracks, which items can be a FullTrack or FullEpisode
+    /// </summary>
+    /// <value></value>
     public Paging<PlaylistTrack<IPlayableItem>> Tracks { get; set; } = default!;
     public string Type { get; set; } = default!;
     public string Uri { get; set; } = default!;
diff --git a/SpotifyAPI.Web/Models/Response/SimplePlaylist.cs b/SpotifyAPI.Web/Models/Response/SimplePlaylist.cs
index 125fb6d3..3dc42554 100644
--- a/SpotifyAPI.Web/Models/Response/SimplePlaylist.cs
+++ b/SpotifyAPI.Web/Models/Response/SimplePlaylist.cs
@@ -16,6 +16,11 @@ namespace SpotifyAPI.Web
     public PublicUser Owner { get; set; } = default!;
     public bool? Public { get; set; }
     public string SnapshotId { get; set; } = default!;
+
+    /// <summary>
+    /// A list of PlaylistTracks, which items can be a FullTrack or FullEpisode
+    /// </summary>
+    /// <value></value>
     public Paging<PlaylistTrack<IPlayableItem>> Tracks { get; set; } = default!;
     public string Type { get; set; } = default!;
     public string Uri { get; set; } = default!;