Add documentation for updating and creating playlist

Sources/MusadoraKit/Add Resources/CreatePlaylist.swift

@@ -1,4 +1,9 @@
 //
+//  "So, I heard you whisper my name,
+//  At once, I knew it was always me.
+//  I cling to all the moments that we shared,
+//  Nobody else could ever compare."
+//
 //  CreatePlaylist.swift
 //  MusadoraKit
 //
@@ -7,79 +12,187 @@
 
 import Foundation
 
-
 @available(macOS 14.0, *)
 public extension MLibrary {
 
-  /// Creates a playlist in the user’s music library.
+  /// Creates a new playlist in the user’s music library.
+  ///
+  /// Use this function to create a new playlist with the given name, description, and author's display name.
+  /// If the author name is not provided, the playlist will be created with your app's name as the author.
+  /// The description for the playlist is optional and can be used to provide additional details about the playlist.
+  ///
+  /// Example usage:
+  ///
+  ///     let playlistName = "My Awesome Playlist"
+  ///     let authorName = "DJ Cool"
+  ///     let playlistDescription = "A playlist full of cool tracks"
+  ///
+  ///     do {
+  ///         let newPlaylist = try await MLibrary.createPlaylist(with: playlistName, author: authorName, description: playlistDescription)
+  ///         print("New playlist created: \(newPlaylist.name)")
+  ///     } catch {
+  ///         print("Failed to create playlist: \(error)")
+  ///     }
   ///
   /// - Parameters:
   ///   - name: The name of the playlist.
-  ///   - author: The display name of the author for the playlist.
-  ///     A `nil` value will use your app’s name.
-  ///   - description: An optional description of the playlist.
-  /// - Returns: The newly created playlist.
+  ///   - author: An optional string containing the author's display name. If this is `nil`, your app's name will be used as the author's name.
+  ///   - description: An optional string describing the playlist.
+  /// - Returns: A `Playlist` object representing the newly created playlist.
+  /// - Throws: An error if the playlist could not be created.
   @available(iOS 16.0, tvOS 16.0, watchOS 9.0, *)
   @available(macOS, unavailable)
   @available(macCatalyst, unavailable)
   static func createPlaylist(with name: String, author: String? = nil, description: String? = nil) async throws -> Playlist {
     try await MusicLibrary.shared.createPlaylist(name: name, description: description, authorDisplayName: author)
   }
 
-  /// Creates a playlist in the user’s music library.
+  /// Creates a new playlist in the user’s music library with a set of songs.
+  ///
+  /// Use this function to create a new playlist with the given name, description, author's display name, and songs.
+  /// If the author name is not provided, the playlist will be created with your app's name as the author.
+  /// The description for the playlist is optional and can be used to provide additional details about the playlist.
+  ///
+  /// Example usage:
+  ///
+  ///     let playlistName = "My Awesome Playlist"
+  ///     let authorName = "DJ Cool"
+  ///     let playlistDescription = "A playlist full of cool tracks"
+  ///     let songs: Songs = [...] // Initialize with the desired songs
+  ///
+  ///     do {
+  ///         let newPlaylist = try await MLibrary.createPlaylist(with: playlistName, author: authorName, description: playlistDescription, items: songs)
+  ///         print("New playlist created: \(newPlaylist.name)")
+  ///     } catch {
+  ///         print("Failed to create playlist: \(error)")
+  ///     }
   ///
   /// - Parameters:
   ///   - name: The name of the playlist.
-  ///   - author: The display name of the author for the playlist.
-  ///     A `nil` value will use your app’s name.
-  ///   - description: An optional description of the playlist.
-  ///   - items: The songs to add to the playlist.
-  /// - Returns: The newly created playlist.
+  ///   - author: An optional string containing the author's display name. If this is `nil`, your app's name will be used as the author's name.
+  ///   - description: An optional string describing the playlist.
+  ///   - items: A `Songs` object representing the songs to be added to the playlist.
+  /// - Returns: A `Playlist` object representing the newly created playlist.
+  /// - Throws: An error if the playlist could not be created.
   @available(iOS 16.0, tvOS 16.0, watchOS 9.0, *)
   @available(macOS, unavailable)
-  @available(macCatalyst, unavailable)  static func createPlaylist(with name: String, author: String? = nil, description: String? = nil, items: Songs) async throws -> Playlist {
+  @available(macCatalyst, unavailable)
+  static func createPlaylist(with name: String, author: String? = nil, description: String? = nil, items: Songs) async throws -> Playlist {
     try await MusicLibrary.shared.createPlaylist(name: name, description: description, authorDisplayName: author, items: items)
   }
 
-  /// Creates a playlist in the user’s music library.
+  /// Creates a new playlist in the user’s music library.
+  ///
+  /// Use this function to create a new playlist in the user's library. Provide a name for the playlist, and an optional description.
+  ///
+  /// Example usage:
+  ///
+  ///     let playlistName = "My Favorite Songs"
+  ///     let playlistDescription = "A collection of my all-time favorite songs."
+  ///
+  ///     do {
+  ///         let newPlaylist = try await MLibrary.createPlaylist(with: playlistName, description: playlistDescription)
+  ///         print("New playlist created: \(newPlaylist.name)")
+  ///     } catch {
+  ///         print("Failed to create playlist: \(error)")
+  ///     }
   ///
   /// - Parameters:
-  ///   - name: The name of the playlist.
-  ///   - description: An optional description of the playlist.
-  /// - Returns: The newly created playlist.
+  ///   - name: The name for the new playlist.
+  ///   - description: An optional description for the playlist.
+  /// - Returns: A `Playlist` object representing the newly created playlist.
+  /// - Throws: An error if the playlist could not be created.
+  /// - Note: This method uses the `LibraryPlaylistCreationRequest` which is available only for iOS 15 and older versions.
   static func createPlaylist(with name: String, description: String? = nil) async throws -> Playlist {
     let creationRequest = LibraryPlaylistCreationRequest(attributes: .init(name: name, description: description))
     return try await createPlaylist(with: creationRequest)
   }
 
-  /// Creates a playlist in the user’s music library with songs.
+  /// Creates a new playlist in the user’s music library and adds songs to it.
+  ///
+  /// Use this function to create a new playlist in the user's library. Provide a name for the playlist, an optional description, and a list of songs to be added to the playlist.
+  ///
+  /// Example usage:
+  ///
+  ///     let playlistName = "My Favorite Songs"
+  ///     let playlistDescription = "A collection of my all-time favorite songs."
+  ///     let songs = [song1, song2, song3] // Assume these are existing Song objects
+  ///
+  ///     do {
+  ///         let newPlaylist = try await MLibrary.createPlaylist(with: playlistName, description: playlistDescription, items: songs)
+  ///         print("New playlist created: \(newPlaylist.name)")
+  ///     } catch {
+  ///         print("Failed to create playlist: \(error)")
+  ///     }
   ///
   /// - Parameters:
-  ///   - name: The name of the playlist.
-  ///   - description: An optional description of the playlist.
-  ///   - items: Add the songs to the playlist.
-  /// - Returns: The newly created playlist.
+  ///   - name: The name for the new playlist.
+  ///   - description: An optional description for the playlist.
+  ///   - items: A list of `Song` objects to be added to the playlist.
+  /// - Returns: A `Playlist` object representing the newly created playlist.
+  /// - Throws: An error if the playlist could not be created.
   static func createPlaylist(with name: String, description: String? = nil, items: Songs) async throws -> Playlist {
     let tracksData: [PlaylistCreationData] = items.map { .init(id: $0.id.rawValue, type: .song)}
 
     let creationRequest = LibraryPlaylistCreationRequest(attributes: .init(name: name, description: description), relationships: .init(tracks: .init(data: tracksData)))
     return try await createPlaylist(with: creationRequest)
   }
 
-  /// Creates a playlist in the user’s music library with song IDs.
+  /// Creates a new playlist in the user’s music library using song identifiers.
+  ///
+  /// Use this function to create a new playlist in the user's library with a given list of song identifiers.
+  /// Provide a name for the playlist, an optional description, and an array of song identifiers.
+  ///
+  /// Example usage:
+  ///
+  ///     let playlistName = "My Favorite Songs"
+  ///     let playlistDescription = "A collection of my all-time favorite songs."
+  ///     let songIDs = ["id1", "id2", "id3"] // Assume these are valid song identifiers
+  ///
+  ///     do {
+  ///         let newPlaylist = try await MLibrary.createPlaylist(with: playlistName, description: playlistDescription, songIds: songIDs)
+  ///         print("New playlist created: \(newPlaylist.name)")
+  ///     } catch {
+  ///         print("Failed to create playlist: \(error)")
+  ///     }
   ///
   /// - Parameters:
-  ///   - name: The name of the playlist.
-  ///   - description: An optional description of the playlist.
-  ///   - songIds: IDs of Songs
-  /// - Returns: The newly created playlist.
+  ///   - name: The name for the new playlist.
+  ///   - description: An optional description for the playlist.
+  ///   - songIds: An array of song identifiers. These are used to add songs to the new playlist.
+  /// - Returns: A `Playlist` object representing the newly created playlist.
+  /// - Throws: An error if the playlist could not be created.
   static func createPlaylist(with name: String, description: String? = nil, songIds: [MusicItemID]) async throws -> Playlist {
     let tracksData: [PlaylistCreationData] = songIds.map { .init(id: $0.rawValue, type: .song) }
 
     let creationRequest = LibraryPlaylistCreationRequest(attributes: .init(name: name, description: description), relationships: .init(tracks: .init(data: tracksData)))
     return try await createPlaylist(with: creationRequest)
   }
 
+  /// Creates a new playlist in the user’s music library using track objects.
+  ///
+  /// This function is used to create a new playlist in the user's music library with a given list of track objects.
+  /// Provide a name for the playlist, an optional description, and an array of track objects.
+  ///
+  /// Example usage:
+  ///
+  ///     let playlistName = "My Favorite Tracks"
+  ///     let playlistDescription = "A collection of my all-time favorite tracks."
+  ///     let trackItems: [Tracks] = ... // Obtain these from the music library
+  ///
+  ///     do {
+  ///         let newPlaylist = try await MLibrary.createPlaylist(with: playlistName, description: playlistDescription, items: trackItems)
+  ///         print("New playlist created: \(newPlaylist.name)")
+  ///     } catch {
+  ///         print("Failed to create playlist: \(error)")
+  ///     }
+  ///
+  /// - Parameters:
+  ///   - name: The name for the new playlist.
+  ///   - description: An optional description for the playlist.
+  ///   - items: An array of track objects. These are used to add tracks to the new playlist.
+  /// - Returns: A `Playlist` object representing the newly created playlist.
+  /// - Throws: An error if the playlist could not be created.
   static func createPlaylist(with name: String, description: String? = nil, items: Tracks) async throws -> Playlist {
     let tracksData: [PlaylistCreationData] = try items.compactMap {
       let data = try JSONEncoder().encode($0.playParameters)
@@ -107,6 +220,31 @@ public extension MLibrary {
     return try await createPlaylist(with: creationRequest)
   }
 
+  /// Creates a new playlist in the user’s music library using an array of playlist-addable items.
+  ///
+  /// This function creates a new playlist in the user's music library. You provide a name for the playlist, an optional description, and an array of playlist-addable items.
+  ///
+  /// Example usage:
+  ///
+  ///     let playlistName = "My Favorite Songs"
+  ///     let playlistDescription = "A collection of my favorite songs."
+  ///     let playlistItems: [any PlaylistAddable] = ... // Obtain these from the music library
+  ///
+  ///     do {
+  ///         let newPlaylist = try await MLibrary.createPlaylist(with: playlistName, description: playlistDescription, items: playlistItems)
+  ///         print("New playlist created: \(newPlaylist.name)")
+  ///     } catch {
+  ///         print("Failed to create playlist: \(error)")
+  ///     }
+  ///
+  /// - Parameters:
+  ///   - name: The name for the new playlist.
+  ///   - description: An optional description for the playlist.
+  ///   - items: An array of items conforming to the `PlaylistAddable` protocol. These are used to add tracks to the new playlist.
+  /// - Returns: A `Playlist` object representing the newly created playlist.
+  /// - Throws: An error if the playlist could not be created.
+  ///
+  /// - Note: The array of items (`[any PlaylistAddable]`) should contain items conforming to the `PlaylistAddable` protocol. This means they should have a `playParameters` property that includes an `id` and a `kind` ("song" or "musicVideo"). The function will also check whether the item is from the library or not using the `isLibrary` property. Depending on these properties, the function will add the item to the playlist.
   static func createPlaylist(with name: String, description: String? = nil, items: [any PlaylistAddable]) async throws -> Playlist {
     let tracksData: [PlaylistCreationData] = try items.compactMap {
       let data = try JSONEncoder().encode($0.playParameters)
@@ -132,10 +270,33 @@ public extension MLibrary {
 
     let creationRequest = LibraryPlaylistCreationRequest(attributes: .init(name: name, description: description), relationships: .init(tracks: .init(data: tracksData)))
     return try await createPlaylist(with: creationRequest)
-
   }
 
-  @discardableResult static func add(songIDs: [MusicItemID], to playlistID: MusicItemID) async throws -> Bool {
+  /// Adds an array of songs, identified by their IDs, to a specified playlist in the user's music library.
+  ///
+  /// Example usage:
+  ///
+  ///     let songIDs: [MusicItemID] = ... // Obtain these from the music library
+  ///     let playlistID: MusicItemID = ... // Obtain this from the music library
+  ///
+  ///     do {
+  ///         let success = try await MLibrary.add(songIDs: songIDs, to: playlistID)
+  ///         if success {
+  ///             print("Songs successfully added to playlist.")
+  ///         } else {
+  ///             print("Failed to add songs to playlist.")
+  ///         }
+  ///     } catch {
+  ///         print("Error adding songs to playlist: \(error)")
+  ///     }
+  ///
+  /// - Parameters:
+  ///   - songIDs: An array of `MusicItemID` objects representing the songs to be added to the playlist.
+  ///   - playlistID: A `MusicItemID` object representing the playlist to which the songs should be added.
+  /// - Returns: A Boolean value indicating whether the songs were successfully added to the playlist.
+  /// - Throws: An error if the songs could not be added to the playlist.
+  @discardableResult
+  static func add(songIDs: [MusicItemID], to playlistID: MusicItemID) async throws -> Bool {
     let songData = songIDs.map { PlaylistCreationData(id: $0.rawValue, type: .song) }
     let tracks = PlaylistCreationTracks(data: songData)
 
@@ -152,7 +313,32 @@ public extension MLibrary {
     return response.urlResponse.statusCode == 201
   }
 
-  @discardableResult static func add(songs: Songs, to playlist: Playlist) async throws -> Bool {
+  /// Adds an array of songs to a specified playlist in the user's music library.
+  ///
+  /// Example usage:
+  ///
+  ///     let songs: [Song] = ... // Obtain these from the music library
+  ///     let playlist: Playlist = ... // Obtain this from the music library
+  ///
+  ///     do {
+  ///         let success = try await MLibrary.add(songs: songs, to: playlist)
+  ///
+  ///         if success {
+  ///             print("Songs successfully added to playlist.")
+  ///         } else {
+  ///             print("Failed to add songs to playlist.")
+  ///         }
+  ///     } catch {
+  ///         print("Error adding songs to playlist: \(error)")
+  ///     }
+  ///
+  /// - Parameters:
+  ///   - songs: An array of `Song` objects representing the songs to be added to the playlist.
+  ///   - playlist: A `Playlist` object representing the playlist to which the songs should be added.
+  /// - Returns: A Boolean value indicating whether the songs were successfully added to the playlist.
+  /// - Throws: An error if the songs could not be added to the playlist.
+  @discardableResult
+  static func add(songs: Songs, to playlist: Playlist) async throws -> Bool {
     try await add(songIDs: songs.map(\.id), to: playlist.id)
   }
 
@@ -178,4 +364,3 @@ public extension MLibrary {
     return playlist
   }
 }
-