Merge pull request #191 from absidue/improve-deezer-docs

Significantly improve the docs for the Deezer classes and functions

play-dl/Deezer/classes.ts

@@ -1,50 +1,169 @@
 import { request } from '../Request';
 
+/**
+ * Interface representing an image on Deezer
+ * available in four sizes
+ */
 interface DeezerImage {
+    /**
+     * The largest version of the image
+     */
     xl: string;
+    /**
+     * The second largest version of the image
+     */
     big: string;
+    /**
+     * The second smallest version of the image
+     */
     medium: string;
+    /**
+     * The smallest version of the image
+     */
     small: string;
 }
 
+/**
+ * Interface representing a Deezer genre
+ */
 interface DeezerGenre {
+    /**
+     * The name of the genre
+     */
     name: string;
+    /**
+     * The thumbnail of the genre available in four sizes
+     */
     picture: DeezerImage;
 }
 
+/**
+ * Interface representing a Deezer user account
+ */
 interface DeezerUser {
+    /**
+     * The id of the user
+     */
     id: number;
+    /**
+     * The name of the user
+     */
     name: string;
 }
 
 /**
- * Class for Deezer Tracks
+ * Class representing a Deezer track
  */
 export class DeezerTrack {
+    /**
+     * The id of the track
+     */
     id: number;
+    /**
+     * The title of the track
+     */
     title: string;
+    /**
+     * A shorter version of the title
+     */
     shortTitle: string;
+    /**
+     * The URL of the track on Deezer
+     */
     url: string;
+    /**
+     * The duration of the track in seconds
+     */
     durationInSec: number;
+    /**
+     * The rank of the track
+     */
     rank: number;
+    /**
+     * `true` if the track contains any explicit lyrics
+     */
     explicit: boolean;
+    /**
+     * URL to a file containing the first 30 seconds of the track
+     */
     previewURL: string;
+    /**
+     * The artist of the track
+     */
     artist: DeezerArtist;
+    /**
+     * The album that this track is in
+     */
     album: DeezerTrackAlbum;
+    /**
+     * The type, always `'track'`, useful to determine what the deezer function returned
+     */
     type: 'track' | 'playlist' | 'album';
 
     /**
-     * true for tracks in search results and false if the track was fetched directly.
+     * Signifies that some properties are not populated
+     *
+     * Partial tracks can be populated by calling {@link DeezerTrack.fetch}.
+     *
+     * `true` for tracks in search results and `false` if the track was fetched directly or expanded.
      */
     partial: boolean;
 
+    /**
+     * The position of the track in the album
+     *
+     * `undefined` for partial tracks
+     *
+     * @see {@link DeezerTrack.partial}
+     */
     trackPosition?: number;
+    /**
+     * The number of the disk the track is on
+     *
+     * `undefined` for partial tracks
+     *
+     * @see {@link DeezerTrack.partial}
+     */
     diskNumber?: number;
+    /**
+     * The release date
+     *
+     * `undefined` for partial tracks
+     *
+     * @see {@link DeezerTrack.partial}
+     */
     releaseDate?: Date;
+    /**
+     * The number of beats per minute
+     *
+     * `undefined` for partial tracks
+     *
+     * @see {@link DeezerTrack.partial}
+     */
     bpm?: number;
+    /**
+     * The gain of the track
+     *
+     * `undefined` for partial tracks
+     *
+     * @see {@link DeezerTrack.partial}
+     */
     gain?: number;
+    /**
+     * The artists that have contributed to the track
+     *
+     * `undefined` for partial tracks
+     *
+     * @see {@link DeezerTrack.partial}
+     */
     contributors?: DeezerArtist[];
 
+    /**
+     * Creates a Deezer track from the data in an API response
+     * @param data the data to use to create the track
+     * @param partial Whether the track should be partial
+     * @see {@link DeezerTrack.partial}
+     */
     constructor(data: any, partial: boolean) {
         this.id = data.id;
         this.title = data.title;
@@ -75,7 +194,11 @@ export class DeezerTrack {
     }
 
     /**
-     * Fetches the missing data for a partial {@link DeezerTrack}.
+     * Fetches and populates the missing fields
+     *
+     * The property {@link partial} will be `false` if this method finishes successfully.
+     *
+     * @returns A promise with the same track this method was called on.
      */
     async fetch(): Promise<DeezerTrack> {
         if (!this.partial) return this;
@@ -100,7 +223,10 @@ export class DeezerTrack {
 
         return this;
     }
-
+    /**
+     * Converts instances of this class to JSON data
+     * @returns JSON data.
+     */
     toJSON() {
         return {
             id: this.id,
@@ -127,31 +253,126 @@ export class DeezerTrack {
  * Class for Deezer Albums
  */
 export class DeezerAlbum {
+    /**
+     * The id of the album
+     */
     id: number;
+    /**
+     * The title of the album
+     */
     title: string;
+    /**
+     * The URL to the album on Deezer
+     */
     url: string;
+    /**
+     * The record type of the album (e.g. EP, ALBUM, etc ...)
+     */
     recordType: string;
+    /**
+     * `true` if the album contains any explicit lyrics
+     */
     explicit: boolean;
+    /**
+     * The artist of the album
+     */
     artist: DeezerArtist;
+    /**
+     * The album cover available in four sizes
+     */
     cover: DeezerImage;
+    /**
+     * The type, always `'album'`, useful to determine what the deezer function returned
+     */
     type: 'track' | 'playlist' | 'album';
+    /**
+     * The number of tracks in the album
+     */
     tracksCount: number;
 
     /**
-     * true for albums in search results and false if the album was fetched directly.
+     * Signifies that some properties are not populated
+     *
+     * Partial albums can be populated by calling {@link DeezerAlbum.fetch}.
+     *
+     * `true` for albums in search results and `false` if the album was fetched directly or expanded.
      */
     partial: boolean;
 
+    /**
+     * The **u**niversal **p**roduct **c**ode of the album
+     *
+     * `undefined` for partial albums
+     *
+     * @see {@link DeezerAlbum.partial}
+     */
     upc?: string;
+    /**
+     * The duration of the album in seconds
+     *
+     * `undefined` for partial albums
+     *
+     * @see {@link DeezerAlbum.partial}
+     */
     durationInSec?: number;
+    /**
+     * The number of fans the album has
+     *
+     * `undefined` for partial albums
+     *
+     * @see {@link DeezerAlbum.partial}
+     */
     numberOfFans?: number;
+    /**
+     * The release date of the album
+     *
+     * `undefined` for partial albums
+     *
+     * @see {@link DeezerAlbum.partial}
+     */
     releaseDate?: Date;
+    /**
+     * Whether the album is available
+     *
+     * `undefined` for partial albums
+     *
+     * @see {@link DeezerAlbum.partial}
+     */
     available?: boolean;
+    /**
+     * The list of genres present in this album
+     *
+     * `undefined` for partial albums
+     *
+     * @see {@link DeezerAlbum.partial}
+     */
     genres?: DeezerGenre[];
+    /**
+     * The contributors to the album
+     *
+     * `undefined` for partial albums
+     *
+     * @see {@link DeezerAlbum.partial}
+     */
     contributors?: DeezerArtist[];
 
+    /**
+     * The list of tracks in the album
+     *
+     * empty (length === 0) for partial albums
+     *
+     * Use {@link DeezerAlbum.fetch} to populate the tracks and other properties
+     *
+     * @see {@link DeezerAlbum.partial}
+     */
     tracks: DeezerTrack[];
 
+    /**
+     * Creates a Deezer album from the data in an API response
+     * @param data the data to use to create the album
+     * @param partial Whether the album should be partial
+     * @see {@link DeezerAlbum.partial}
+     */
     constructor(data: any, partial: boolean) {
         this.id = data.id;
         this.title = data.title;
@@ -213,7 +434,11 @@ export class DeezerAlbum {
     }
 
     /**
-     * Fetches the missing data for a partial {@link DeezerAlbum}.
+     * Fetches and populates the missing fields including all tracks.
+     *
+     * The property {@link DeezerAlbum.partial} will be `false` if this method finishes successfully.
+     *
+     * @returns A promise with the same album this method was called on.
      */
     async fetch(): Promise<DeezerAlbum> {
         if (!this.partial) return this;
@@ -266,7 +491,10 @@ export class DeezerAlbum {
 
         return this;
     }
-
+    /**
+     * Converts instances of this class to JSON data
+     * @returns JSON data.
+     */
     toJSON() {
         return {
             id: this.id,
@@ -290,29 +518,114 @@ export class DeezerAlbum {
     }
 }
 /**
- * Class for Deezer Albums
+ * Class for Deezer Playlists
  */
 export class DeezerPlaylist {
+    /**
+     * The id of the playlist
+     */
     id: number;
+    /**
+     * The title of the playlist
+     */
     title: string;
+    /**
+     * Whether the playlist is public or private
+     */
     public: boolean;
+    /**
+     * The URL of the playlist on Deezer
+     */
     url: string;
+    /**
+     * Cover picture of the playlist available in four sizes
+     */
     picture: DeezerImage;
+    /**
+     * The date of the playlist's creation
+     */
     creationDate: Date;
+    /**
+     * The type, always `'playlist'`, useful to determine what the deezer function returned
+     */
     type: 'track' | 'playlist' | 'album';
+    /**
+     * The Deezer user that created the playlist
+     */
     creator: DeezerUser;
+    /**
+     * The number of tracks in the playlist
+     */
     tracksCount: number;
 
+    /**
+     * Signifies that some properties are not populated
+     *
+     * Partial playlists can be populated by calling {@link DeezerPlaylist.fetch}.
+     *
+     * `true` for playlists in search results and `false` if the album was fetched directly or expanded.
+     */
     partial: boolean;
 
+    /**
+     * Description of the playlist
+     *
+     * `undefined` for partial playlists
+     *
+     * @see {@link DeezerPlaylist.partial}
+     */
     description?: string;
+    /**
+     * Duration of the playlist in seconds
+     *
+     * `undefined` for partial playlists
+     *
+     * @see {@link DeezerPlaylist.partial}
+     */
     durationInSec?: number;
+    /**
+     * `true` if the playlist is the loved tracks playlist
+     *
+     * `undefined` for partial playlists
+     *
+     * @see {@link DeezerPlaylist.partial}
+     */
     isLoved?: boolean;
+    /**
+     * Whether multiple users have worked on the playlist
+     *
+     * `undefined` for partial playlists
+     *
+     * @see {@link DeezerPlaylist.partial}
+     */
     collaborative?: boolean;
+    /**
+     * The number of fans the playlist has
+     *
+     * `undefined` for partial playlists
+     *
+     * @see {@link DeezerPlaylist.partial}
+     */
     fans?: number;
 
+    /**
+     * The list of tracks in the playlist
+     *
+     * empty (length === 0) for partial and non public playlists
+     *
+     * Use {@link DeezerPlaylist.fetch} to populate the tracks and other properties
+     *
+     * @see {@link DeezerPlaylist.partial}
+     * @see {@link DeezerPlaylist.public}
+     */
     tracks: DeezerTrack[];
 
+    /**
+     * Creates a Deezer playlist from the data in an API response
+     * @param data the data to use to create the playlist
+     * @param partial Whether the playlist should be partial
+     * @see {@link DeezerPlaylist.partial}
+     */
     constructor(data: any, partial: boolean) {
         this.id = data.id;
         this.title = data.title;
@@ -360,8 +673,11 @@ export class DeezerPlaylist {
     }
 
     /**
-     * Fetches the missing data for a partial {@link DeezerPlaylist} as well as fetching all tracks.
+     * Fetches and populates the missing fields, including all tracks.
-     * @returns The Deezer playlist object this method was called on.
+     *
+     * The property {@link DeezerPlaylist.partial} will be `false` if this method finishes successfully.
+     *
+     * @returns A promise with the same playlist this method was called on.
      */
     async fetch(): Promise<DeezerPlaylist> {
         if (!this.partial && (this.tracks.length === this.tracksCount || !this.public)) {
@@ -430,7 +746,10 @@ export class DeezerPlaylist {
 
         return this;
     }
-
+    /**
+     * Converts instances of this class to JSON data
+     * @returns JSON data.
+     */
     toJSON() {
         return {
             id: this.id,
@@ -473,12 +792,30 @@ class DeezerTrackAlbum {
         if (data.release_date) this.releaseDate = new Date(data.release_date);
     }
 }
-
+/**
+ * Class representing a Deezer artist
+ */
 class DeezerArtist {
+    /**
+     * The id of the artist
+     */
     id: number;
+    /**
+     * The name of the artist
+     */
     name: string;
+    /**
+     * The URL of the artist on Deezer
+     */
     url: string;
+
+    /**
+     * The picture of the artist available in four sizes
+     */
     picture?: DeezerImage;
+    /**
+     * The of the artist on the track
+     */
     role?: string;
 
     constructor(data: any) {

play-dl/Deezer/index.ts

@@ -9,20 +9,56 @@ interface TypeData {
 }
 
 interface DeezerSearchOptions {
+    /**
+     * The type to search for `'track'`, `'playlist'` or `'album'`. Defaults to `'track'`.
+     */
     type?: 'track' | 'playlist' | 'album';
+    /**
+     * The maximum number of results to return, maximum `100`, defaults to `10`.
+     */
     limit?: number;
+    /**
+     * Whether the search should be fuzzy or only return exact matches. Defaults to `true`.
+     */
     fuzzy?: boolean;
 }
 
 interface DeezerAdvancedSearchOptions {
+    /**
+     * The maximum number of results to return, maximum `100`, defaults to `10`.
+     */
     limit?: number;
+    /**
+     * The name of the artist.
+     */
     artist?: string;
+    /**
+     * The title of the album.
+     */
     album?: string;
+    /**
+     * The title of the track.
+     */
     title?: string;
+    /**
+     * The label that released the track.
+     */
     label?: string;
+    /**
+     * The minimum duration in seconds.
+     */
     minDurationInSec?: number;
+    /**
+     * The maximum duration in seconds.
+     */
     maxDurationInSec?: number;
+    /**
+     * The minimum BPM.
+     */
     minBPM?: number;
+    /**
+     * The minimum BPM.
+     */
     maxBPM?: number;
 }
 
@@ -139,8 +175,8 @@ export async function deezer(url: string): Promise<Deezer> {
 /**
  * Validates a Deezer URL
  * @param url The URL to validate
- * @returns The type of the URL either 'track', 'playlist', 'album', 'search' or false.
+ * @returns The type of the URL either `'track'`, `'playlist'`, `'album'`, `'search'` or `false`.
- * false means that the provided URL was a wrongly formatted or unsupported Deezer URL.
+ * `false` means that the provided URL was a wrongly formatted or an unsupported Deezer URL.
  */
 export async function dz_validate(url: string): Promise<'track' | 'playlist' | 'album' | 'search' | false> {
     const typeData = await internalValidate(url);