From 029ae9b8f35b76105b7dabadf0646aedcea28156 Mon Sep 17 00:00:00 2001
From: killer069 <65385476+killer069@users.noreply.github.com>
Date: Mon, 22 Nov 2021 16:03:33 +0530
Subject: [PATCH] Some more documentation work (90% complete)

---
 play-dl/SoundCloud/index.ts | 39 ++++++++++++++++++++++++------
 play-dl/Spotify/index.ts    | 48 +++++++++++++++++++++++++++++--------
 play-dl/index.ts            |  2 +-
 play-dl/token.ts            | 13 +++++++++-
 4 files changed, 83 insertions(+), 19 deletions(-)

diff --git a/play-dl/SoundCloud/index.ts b/play-dl/SoundCloud/index.ts
index 4b284c5..239ddd6 100644
--- a/play-dl/SoundCloud/index.ts
+++ b/play-dl/SoundCloud/index.ts
@@ -13,9 +13,20 @@ interface SoundDataOptions {
 
 const pattern = /^(?:(https?):\/\/)?(?:(?:www|m)\.)?(api\.soundcloud\.com|soundcloud\.com|snd\.sc)\/(.*)$/;
 /**
- * Function to get info from a soundcloud url
+ * Gets info from a soundcloud url.
+ * 
+ * ```ts
+ * let sound = await play.soundcloud('soundcloud url')
+ * 
+ * // sound.type === "track" | "playlist" | "user"
+ * 
+ * if (sound.type === "track") {
+ *      spot = spot as play.SoundCloudTrack
+ *      // Code with SoundCloud track class.
+ * }
+ * ```
  * @param url soundcloud url
- * @returns SoundCloud Track or SoundCloud Playlist
+ * @returns A {@link SoundCloudTrack} or {@link SoundCloudPlaylist}
  */
 export async function soundcloud(url: string): Promise<SoundCloud> {
     if (!soundData) throw new Error('SoundCloud Data is missing\nDid you forgot to do authorization ?');
@@ -85,7 +96,17 @@ export async function stream(url: string, quality?: number): Promise<SoundCloudS
     return new SoundCloudStream(s_data.url, type);
 }
 /**
- * Function to get Free Client ID of soundcloud.
+ * Gets Free SoundCloud Client ID.
+ * 
+ * Use this in beginning of your code to add SoundCloud support.
+ * 
+ * ```ts
+ * play.getFreeClientID().then((clientID) => play.setToken({
+ *      soundcloud : {
+ *          client_id : clientID
+ *      }
+ * }))
+ * ```
  * @returns client ID
  */
 export async function getFreeClientID(): Promise<string> {
@@ -133,12 +154,16 @@ export async function check_id(id: string): Promise<boolean> {
     else return true;
 }
 /**
- * Function to validate for a soundcloud url
+ * Validates a soundcloud url
  * @param url soundcloud url
- * @returns "false" | 'track' | 'playlist'
+ * @returns 
+ * ```ts
+ * false | 'track' | 'playlist'
+ * ```
  */
 export async function so_validate(url: string): Promise<false | 'track' | 'playlist' | 'search'> {
-    if (!url.match(pattern)) return 'search';
+    if (!url.startsWith('https')) return 'search';
+    if (!url.match(pattern)) return false;
     const data = await request(
         `https://api-v2.soundcloud.com/resolve?url=${url}&client_id=${soundData.client_id}`
     ).catch((err: Error) => err);
@@ -153,7 +178,7 @@ export async function so_validate(url: string): Promise<false | 'track' | 'playl
 /**
  * Function to select only hls streams from SoundCloud format array
  * @param data SoundCloud Track Format data
- * @returns a new array containing hls formats
+ * @returns HLS Formats Array
  */
 function parseHlsFormats(data: SoundCloudTrackFormat[]) {
     const result: SoundCloudTrackFormat[] = [];
diff --git a/play-dl/Spotify/index.ts b/play-dl/Spotify/index.ts
index c8d1df3..69b65b2 100644
--- a/play-dl/Spotify/index.ts
+++ b/play-dl/Spotify/index.ts
@@ -26,9 +26,20 @@ export interface SpotifyDataOptions {
 
 const pattern = /^((https:)?\/\/)?open.spotify.com\/(track|album|playlist)\//;
 /**
- * Function to get Playlist | Album | Track
- * @param url url of spotify from which you want info
- * @returns Spotify type.
+ * Gets Spotify url details.
+ * 
+ * ```ts
+ * let spot = await play.spotify('spotify url')
+ * 
+ * // spot.type === "track" | "playlist" | "album"
+ * 
+ * if (spot.type === "track") {
+ *      spot = spot as play.SpotifyTrack
+ *      // Code with spotify track class.
+ * }
+ * ```
+ * @param url Spotify Url
+ * @returns A {@link SpotifyTrack} or {@link SpotifyPlaylist} or {@link SpotifyAlbum}
  */
 export async function spotify(url: string): Promise<Spotify> {
     if (!spotifyData) throw new Error('Spotify Data is missing\nDid you forgot to do authorization ?');
@@ -72,12 +83,16 @@ export async function spotify(url: string): Promise<Spotify> {
     } else throw new Error('URL is out of scope for play-dl.');
 }
 /**
- * Function to validate Spotify url
- * @param url url for validation
- * @returns type of url or false.
+ * Validate Spotify url
+ * @param url Spotify URL
+ * @returns 
+ * ```ts
+ * 'track' | 'playlist' | 'album' | 'search' | false
+ * ```
  */
 export function sp_validate(url: string): 'track' | 'playlist' | 'album' | 'search' | false {
-    if (!url.match(pattern)) return 'search';
+    if (!url.startsWith('https')) return 'search';
+    if (!url.match(pattern)) return false;
     if (url.indexOf('track/') !== -1) {
         return 'track';
     } else if (url.indexOf('album/') !== -1) {
@@ -128,7 +143,14 @@ export async function SpotifyAuthorize(data: SpotifyDataOptions, file: boolean):
     return true;
 }
 /**
- * Function to check if authorization token is expired or not.
+ * Checks if spotify token is expired or not.
+ * 
+ * Update token if returned false.
+ * ```ts
+ * if (!play.is_expired()) {
+ *      await play.refreshToken()
+ * }
+ * ```
  * @returns boolean
  */
 export function is_expired(): boolean {
@@ -183,8 +205,14 @@ export async function sp_search(
     return results;
 }
 /**
- * Function to refresh Token
- * @returns boolean to check whether token is refreshed or not
+ * Refreshes Token
+ * 
+ * ```ts
+ * if (!play.is_expired()) {
+ *      await play.refreshToken()
+ * }
+ * ```
+ * @returns boolean
  */
 export async function refreshToken(): Promise<boolean> {
     const response = await request(`https://accounts.spotify.com/api/token`, {
diff --git a/play-dl/index.ts b/play-dl/index.ts
index 78bafb0..3ca0ff4 100644
--- a/play-dl/index.ts
+++ b/play-dl/index.ts
@@ -61,13 +61,13 @@ import { YouTubePlayList } from './YouTube/classes/Playlist';
 import { YouTubeChannel } from './YouTube/classes/Channel';
 import { SpotifyAlbum, SpotifyPlaylist, SpotifyTrack } from './Spotify/classes';
 import { DeezerAlbum, DeezerPlaylist, DeezerTrack } from './Deezer/classes';
+
 /**
  * Main stream Command for streaming through various sources
  * @param url The video / track url to make stream of
  * @param options contains quality, cookie and proxy to set for stream
  * @returns YouTube / SoundCloud Stream to play
  */
-
 export async function stream(url: string, options: StreamOptions = {}): Promise<YouTubeStream | SoundCloudStream> {
     if (url.length === 0) throw new Error('Stream URL has a length of 0. Check your url again.');
     if (url.indexOf('spotify') !== -1) {
diff --git a/play-dl/token.ts b/play-dl/token.ts
index 17237b9..89600b8 100644
--- a/play-dl/token.ts
+++ b/play-dl/token.ts
@@ -16,7 +16,18 @@ interface tokenOptions {
         cookie: string;
     };
 }
-
+/**
+ * Sets 
+ * 
+ *  i> YouTube :- cookies.
+ * 
+ *  ii> SoundCloud :- client ID.
+ * 
+ *  iii> Spotify :- client ID, client secret, refresh token, market.
+ * 
+ * locally in memory.
+ * @param options {@link tokenOptions}
+ */
 export function setToken(options: tokenOptions) {
     if (options.spotify) setSpotifyToken(options.spotify);
     if (options.soundcloud) setSoundCloudToken(options.soundcloud);