mirror of
https://github.com/koel/koel
synced 2024-11-10 06:34:14 +00:00
Better jsdoc
This commit is contained in:
parent
d32fda6342
commit
c017a8dab6
20 changed files with 90 additions and 73 deletions
|
@ -170,8 +170,8 @@
|
|||
/**
|
||||
* Load (display) a main panel (view).
|
||||
*
|
||||
* @param string view The view, which can be found under components/main-wrapper/main-content.
|
||||
* @param [...args] Extra data to attach to the view.
|
||||
* @param {String} view The view, which can be found under components/main-wrapper/main-content.
|
||||
* @param {...*} Extra data to attach to the view.
|
||||
*/
|
||||
loadMainView(view, ...args) {
|
||||
this.$broadcast('main-content-view:load', view, ...args);
|
||||
|
|
|
@ -62,7 +62,7 @@
|
|||
* Listen to 'main-content-view:load' event (triggered from $root currently)
|
||||
* to load the requested album into view if applicable.
|
||||
*
|
||||
* @param {string} view The view name
|
||||
* @param {String} view The view name
|
||||
* @param {Object} album The album object
|
||||
*/
|
||||
'main-content-view:load': function (view, album) {
|
||||
|
|
|
@ -62,7 +62,7 @@
|
|||
* Listen to 'main-content-view:load' event (triggered from $root currently)
|
||||
* to load the requested artist into view if applicable.
|
||||
*
|
||||
* @param {string} view The view's name
|
||||
* @param {String} view The view's name
|
||||
* @param {Object} artist
|
||||
*/
|
||||
'main-content-view:load': function (view, artist) {
|
||||
|
|
|
@ -52,7 +52,7 @@
|
|||
*
|
||||
* @param {Object} song
|
||||
*
|
||||
* @return {boolean}
|
||||
* @return {Boolean}
|
||||
*/
|
||||
'song:played': function (song) {
|
||||
this.albumCover = song.album.cover === albumStore.stub.cover ? null : song.album.cover;
|
||||
|
|
|
@ -76,7 +76,7 @@
|
|||
* Listen to 'main-content-view:load' event (triggered from $root currently)
|
||||
* to load the requested playlist into view if applicable.
|
||||
*
|
||||
* @param {string} view The view's name.
|
||||
* @param {String} view The view's name.
|
||||
* @param {Object} playlist
|
||||
*/
|
||||
'main-content-view:load': function (view, playlist) {
|
||||
|
|
|
@ -136,9 +136,9 @@
|
|||
|
||||
/**
|
||||
* Cancel editing, or simply close the form after updating.
|
||||
* @param {boolean=true} rollback If true, editing was cancelled.
|
||||
* The original state of the edited user must be restored.
|
||||
* If false, editing was successfully committed.
|
||||
* @param {Boolean=true} rollback If true, editing was cancelled.
|
||||
* The original state of the edited user must be restored.
|
||||
* If false, editing was successfully committed.
|
||||
*/
|
||||
cancelEdit(rollback = true) {
|
||||
if (rollback) {
|
||||
|
|
|
@ -103,7 +103,7 @@
|
|||
*
|
||||
* @param {Object} e The event
|
||||
*
|
||||
* @return {boolean}
|
||||
* @return {Boolean}
|
||||
*/
|
||||
handleDrop(e) {
|
||||
this.removeDroppableState(e);
|
||||
|
|
|
@ -125,7 +125,7 @@
|
|||
*
|
||||
* @param {Object} e The event
|
||||
*
|
||||
* @return {boolean}
|
||||
* @return {Boolean}
|
||||
*/
|
||||
handleDrop(e) {
|
||||
this.removeDroppableState(e);
|
||||
|
|
|
@ -103,7 +103,7 @@
|
|||
/**
|
||||
* Init the equalizer.
|
||||
*
|
||||
* @param {Object} player The audio player DOM.
|
||||
* @param {Element} player The audio player's DOM.
|
||||
*/
|
||||
init(player) {
|
||||
var AudioContext = window.AudioContext || window.webkitAudioContext || false;
|
||||
|
|
|
@ -94,7 +94,7 @@
|
|||
/**
|
||||
* Indicate if we should build and use an equalizer.
|
||||
*
|
||||
* @type {boolean}
|
||||
* @type {Boolean}
|
||||
*/
|
||||
useEqualizer: utils.isAudioContextSupported(),
|
||||
};
|
||||
|
@ -116,7 +116,7 @@
|
|||
/**
|
||||
* Get the album cover for the current song.
|
||||
*
|
||||
* @return {?string}
|
||||
* @return {?String}
|
||||
*/
|
||||
cover() {
|
||||
// don't display the default cover here
|
||||
|
@ -235,7 +235,7 @@
|
|||
*
|
||||
* @param {Object} song
|
||||
*
|
||||
* @return {boolean}
|
||||
* @return {Boolean}
|
||||
*/
|
||||
'song:played': function (song) {
|
||||
this.playing = true;
|
||||
|
|
|
@ -23,7 +23,7 @@ export default {
|
|||
/**
|
||||
* An array of selected songs in the list.
|
||||
*
|
||||
* @type {Array}
|
||||
* @type {Array.<Object>}
|
||||
*/
|
||||
selectedSongs: [],
|
||||
|
||||
|
|
|
@ -19,7 +19,7 @@ export default {
|
|||
/**
|
||||
* Initialize the playback service for this whole Koel app.
|
||||
*
|
||||
* @param {Object} app The root Vue component.
|
||||
* @param {Vue} app The root Vue component.
|
||||
*/
|
||||
init(app) {
|
||||
// We don't need to init this service twice, or the media events will be duplicated.
|
||||
|
@ -132,6 +132,8 @@ export default {
|
|||
/**
|
||||
* Get the next song in the queue.
|
||||
* If we're in REPEAT_ALL mode and there's no next song, just get the first song.
|
||||
*
|
||||
* @return {Object} The song
|
||||
*/
|
||||
nextSong() {
|
||||
var next = queueStore.getNextSong();
|
||||
|
@ -148,6 +150,8 @@ export default {
|
|||
/**
|
||||
* Get the prev song in the queue.
|
||||
* If we're in REPEAT_ALL mode and there's no prev song, get the last song.
|
||||
*
|
||||
* @return {Object} The song
|
||||
*/
|
||||
prevSong() {
|
||||
var prev = queueStore.getPrevSong();
|
||||
|
@ -219,8 +223,8 @@ export default {
|
|||
/**
|
||||
* Set the volume level.
|
||||
*
|
||||
* @param {integer} volume 0-10
|
||||
* @param {boolean=true} persist Whether the volume should be saved into local storage
|
||||
* @param {Number} volume 0-10
|
||||
* @param {Boolean=true} persist Whether the volume should be saved into local storage
|
||||
*/
|
||||
setVolume(volume, persist = true) {
|
||||
this.player.setVolume(volume);
|
||||
|
@ -281,8 +285,8 @@ export default {
|
|||
/**
|
||||
* Queue up songs (replace them into the queue) and start playing right away.
|
||||
*
|
||||
* @param {?Array} songs An array of song objects. Defaults to all songs if null.
|
||||
* @param {boolean=false} shuffle Whether to shuffle the songs before playing.
|
||||
* @param {?Array.<Object>} songs An array of song objects. Defaults to all songs if null.
|
||||
* @param {Boolean=false} shuffle Whether to shuffle the songs before playing.
|
||||
*/
|
||||
queueAndPlay(songs = null, shuffle = false) {
|
||||
if (!songs) {
|
||||
|
@ -324,7 +328,7 @@ export default {
|
|||
* Play all songs by an artist.
|
||||
*
|
||||
* @param {Object} artist The artist object
|
||||
* @param {boolean=true} shuffle Whether to shuffle the songs
|
||||
* @param {Boolean=true} shuffle Whether to shuffle the songs
|
||||
*/
|
||||
playAllByArtist(artist, shuffle = true) {
|
||||
this.queueAndPlay(artistStore.getSongsByArtist(artist), true);
|
||||
|
@ -334,7 +338,7 @@ export default {
|
|||
* Play all songs in an album.
|
||||
*
|
||||
* @param {Object} album The album object
|
||||
* @param {boolean=true} shuffle Whether to shuffle the songs
|
||||
* @param {Boolean=true} shuffle Whether to shuffle the songs
|
||||
*/
|
||||
playAllInAlbum(album, shuffle = true) {
|
||||
this.queueAndPlay(album.songs, true);
|
||||
|
|
|
@ -34,7 +34,7 @@ export default {
|
|||
*
|
||||
* @param {Object} error The error object in JSON format.
|
||||
*
|
||||
* @return {Array}
|
||||
* @return {Array.<String>}
|
||||
*/
|
||||
parseValidationError(error) {
|
||||
return Object.keys(error).reduce((messages, field) => messages.concat(error[field]), []);
|
||||
|
@ -43,7 +43,7 @@ export default {
|
|||
/**
|
||||
* Check if AudioContext is supported by the current browser.
|
||||
*
|
||||
* @return {boolean}
|
||||
* @return {Boolean}
|
||||
*/
|
||||
isAudioContextSupported() {
|
||||
// Apple device just doesn't love AudioContext that much.
|
||||
|
|
|
@ -14,7 +14,7 @@ export default {
|
|||
/**
|
||||
* Init the store.
|
||||
*
|
||||
* @param {Array} artists The array of artists to extract album data from.
|
||||
* @param {Array.<Object>} artists The array of artists to extract album data from.
|
||||
*/
|
||||
init(artists) {
|
||||
// Traverse through the artists array and add their albums into our master album list.
|
||||
|
@ -33,6 +33,11 @@ export default {
|
|||
songStore.init(this.state.albums);
|
||||
},
|
||||
|
||||
/**
|
||||
* Get all albums in the store.
|
||||
*
|
||||
* @return {Array.<Object>}
|
||||
*/
|
||||
all() {
|
||||
return this.state.albums;
|
||||
},
|
||||
|
@ -43,7 +48,7 @@ export default {
|
|||
*
|
||||
* @param {Object} album
|
||||
*
|
||||
* @return {string} The H:i:s format of the album length.
|
||||
* @return {String} The H:i:s format of the album length.
|
||||
*/
|
||||
getLength(album) {
|
||||
album.length = _.reduce(album.songs, (length, song) => length + song.length, 0);
|
||||
|
|
|
@ -14,7 +14,7 @@ export default {
|
|||
/**
|
||||
* Init the store.
|
||||
*
|
||||
* @param {Array} artists The array of artists we got from the server.
|
||||
* @param {Array.<Object>} artists The array of artists we got from the server.
|
||||
*/
|
||||
init(artists) {
|
||||
this.state.artists = artists;
|
||||
|
@ -38,7 +38,7 @@ export default {
|
|||
*
|
||||
* @param {Object} artist
|
||||
*
|
||||
* @return {Array}
|
||||
* @return {Array.<Object>}
|
||||
*/
|
||||
getSongsByArtist(artist) {
|
||||
if (!artist.songs) {
|
||||
|
@ -53,7 +53,7 @@ export default {
|
|||
*
|
||||
* @param {Object} artist
|
||||
*
|
||||
* @return {string}
|
||||
* @return {String}
|
||||
*/
|
||||
getImage(artist) {
|
||||
// If the artist already has a proper image, just return it.
|
||||
|
|
|
@ -10,6 +10,11 @@ export default {
|
|||
fmtLength: '',
|
||||
},
|
||||
|
||||
/**
|
||||
* Get all songs favorited by the current user.
|
||||
*
|
||||
* @return {Array.<Object>}
|
||||
*/
|
||||
all() {
|
||||
return this.state.songs;
|
||||
},
|
||||
|
@ -64,8 +69,8 @@ export default {
|
|||
/**
|
||||
* Like a bunch of songs.
|
||||
*
|
||||
* @param {Array} songs
|
||||
* @param {?Function} cb
|
||||
* @param {Array.<Object>} songs
|
||||
* @param {?Function} cb
|
||||
*/
|
||||
like(songs, cb = null) {
|
||||
// Don't wait for the HTTP response to update the status, just set them to Liked right away.
|
||||
|
@ -83,8 +88,8 @@ export default {
|
|||
/**
|
||||
* Unlike a bunch of songs.
|
||||
*
|
||||
* @param {Array} songs
|
||||
* @param {?Function} cb
|
||||
* @param {Array.<Object>} songs
|
||||
* @param {?Function} cb
|
||||
*/
|
||||
unlike(songs, cb = null) {
|
||||
// Don't wait for the HTTP response to update the status, just set them to Unliked right away.
|
||||
|
|
|
@ -17,6 +17,11 @@ export default {
|
|||
_.each(this.state.playlists, this.getSongs);
|
||||
},
|
||||
|
||||
/**
|
||||
* Get all playlists of the current user.
|
||||
*
|
||||
* @return {Array.<Object>}
|
||||
*/
|
||||
all() {
|
||||
return this.state.playlists;
|
||||
},
|
||||
|
@ -24,7 +29,7 @@ export default {
|
|||
/**
|
||||
* Get all songs in a playlist.
|
||||
*
|
||||
* return {Array}
|
||||
* return {Array.<Object>}
|
||||
*/
|
||||
getSongs(playlist) {
|
||||
return (playlist.songs = songStore.byIds(playlist.songs));
|
||||
|
@ -33,9 +38,9 @@ export default {
|
|||
/**
|
||||
* Create a new playlist, optionally with its songs.
|
||||
*
|
||||
* @param {string} name Name of the playlist
|
||||
* @param {Array} songs An array of song objects
|
||||
* @param {?Function} cb
|
||||
* @param {String} name Name of the playlist
|
||||
* @param {Array.<Object>} songs An array of song objects
|
||||
* @param {?Function} cb
|
||||
*/
|
||||
store(name, songs, cb = null) {
|
||||
if (songs.length) {
|
||||
|
@ -74,9 +79,9 @@ export default {
|
|||
/**
|
||||
* Add songs into a playlist.
|
||||
*
|
||||
* @param {Object} playlist
|
||||
* @param {Array} songs
|
||||
* @param {?Function} cb
|
||||
* @param {Object} playlist
|
||||
* @param {Array.<Object>} songs
|
||||
* @param {?Function} cb
|
||||
*/
|
||||
addSongs(playlist, songs, cb = null) {
|
||||
var count = playlist.songs.length;
|
||||
|
@ -96,9 +101,9 @@ export default {
|
|||
/**
|
||||
* Remove songs from a playlist.
|
||||
*
|
||||
* @param {Object} playlist
|
||||
* @param {Array} songs
|
||||
* @param {?Function} cb
|
||||
* @param {Object} playlist
|
||||
* @param {Array.<Object>} songs
|
||||
* @param {?Function} cb
|
||||
*/
|
||||
removeSongs(playlist, songs, cb = null) {
|
||||
playlist.songs = _.difference(playlist.songs, songs);
|
||||
|
|
|
@ -31,8 +31,6 @@ export default {
|
|||
// It's alright
|
||||
// Take anything you want from me
|
||||
// Anything...
|
||||
//
|
||||
// [CRAZY SOLO BITCH!]
|
||||
},
|
||||
|
||||
all() {
|
||||
|
@ -52,7 +50,7 @@ export default {
|
|||
*
|
||||
* @param {Object} song
|
||||
*
|
||||
* @return {boolean}
|
||||
* @return {Boolean}
|
||||
*/
|
||||
contains(song) {
|
||||
return _.includes(this.all(), song);
|
||||
|
@ -62,9 +60,9 @@ export default {
|
|||
* Add a list of songs to the end of the current queue,
|
||||
* or replace the current queue as a whole if `replace` is true.
|
||||
*
|
||||
* @param {Object|Array} songs The song, or an array of songs
|
||||
* @param {boolean} replace Whether to replace the current queue
|
||||
* @param {boolean} toTop Whether to prepend of append to the queue
|
||||
* @param {Object|Array.<Object>} songs The song, or an array of songs
|
||||
* @param {Boolean} replace Whether to replace the current queue
|
||||
* @param {Boolean} toTop Whether to prepend of append to the queue
|
||||
*/
|
||||
queue(songs, replace = false, toTop = false) {
|
||||
if (!Array.isArray(songs)) {
|
||||
|
@ -85,7 +83,7 @@ export default {
|
|||
/**
|
||||
* Queue song(s) to after the current song.
|
||||
*
|
||||
* @param {Array|Object} songs
|
||||
* @param {Array.<Object>|Object} songs
|
||||
*/
|
||||
queueAfterCurrent(songs) {
|
||||
if (!Array.isArray(songs)) {
|
||||
|
@ -103,7 +101,7 @@ export default {
|
|||
/**
|
||||
* Unqueue a song, or several songs at once.
|
||||
*
|
||||
* @param {Object|string|Array} songs The song(s) to unqueue.
|
||||
* @param {Object|String|Array.<Object>} songs The song(s) to unqueue.
|
||||
*/
|
||||
unqueue(songs) {
|
||||
if (!Array.isArray(songs)) {
|
||||
|
@ -116,8 +114,8 @@ export default {
|
|||
/**
|
||||
* Move some songs to after a target.
|
||||
*
|
||||
* @param {Array} songs Songs to move
|
||||
* @param {Object} target The target song object
|
||||
* @param {Array.<Object>} songs Songs to move
|
||||
* @param {Object} target The target song object
|
||||
*/
|
||||
move(songs, target) {
|
||||
var $targetIndex = this.indexOf(target);
|
||||
|
@ -145,7 +143,7 @@ export default {
|
|||
*
|
||||
* @param {Object} song
|
||||
*
|
||||
* @return {?integer}
|
||||
* @return {?Integer}
|
||||
*/
|
||||
indexOf(song) {
|
||||
return _.indexOf(this.state.songs, song);
|
||||
|
|
|
@ -18,7 +18,7 @@ export default {
|
|||
/**
|
||||
* Init the store.
|
||||
*
|
||||
* @param {Array} albums The array of albums to extract our songs from
|
||||
* @param {Array.<Object>} albums The array of albums to extract our songs from
|
||||
*/
|
||||
init(albums) {
|
||||
// Iterate through the albums. With each, add its songs into our master song list.
|
||||
|
@ -41,7 +41,7 @@ export default {
|
|||
/**
|
||||
* Initializes the interaction (like/play count) information.
|
||||
*
|
||||
* @param {Array} interactions The array of interactions of the current user
|
||||
* @param {Array.<Object>} interactions The array of interactions of the current user
|
||||
*/
|
||||
initInteractions(interactions) {
|
||||
favoriteStore.clear();
|
||||
|
@ -65,10 +65,10 @@ export default {
|
|||
/**
|
||||
* Get the total duration of some songs.
|
||||
*
|
||||
* @param {Array} songs
|
||||
* @param {boolean} toHis Wheter to convert the duration into H:i:s format
|
||||
* @param {Array.<Object>} songs
|
||||
* @param {Boolean} toHis Wheter to convert the duration into H:i:s format
|
||||
*
|
||||
* @return {float|string}
|
||||
* @return {Float|String}
|
||||
*/
|
||||
getLength(songs, toHis) {
|
||||
var duration = _.reduce(songs, (length, song) => length + song.length, 0);
|
||||
|
@ -83,7 +83,7 @@ export default {
|
|||
/**
|
||||
* Get all songs.
|
||||
*
|
||||
* @return {Array}
|
||||
* @return {Array.<Object>}
|
||||
*/
|
||||
all() {
|
||||
return this.state.songs;
|
||||
|
@ -92,7 +92,7 @@ export default {
|
|||
/**
|
||||
* Get a song by its ID.
|
||||
*
|
||||
* @param {string} id
|
||||
* @param {String} id
|
||||
*
|
||||
* @return {Object}
|
||||
*/
|
||||
|
@ -103,9 +103,9 @@ export default {
|
|||
/**
|
||||
* Get songs by their IDs.
|
||||
*
|
||||
* @param {Array} ids
|
||||
* @param {Array.<String>} ids
|
||||
*
|
||||
* @return {Array}
|
||||
* @return {Array.<Object>}
|
||||
*/
|
||||
byIds(ids) {
|
||||
return _.map(ids, id => this.byId(id));
|
||||
|
|
|
@ -16,8 +16,8 @@ export default {
|
|||
/**
|
||||
* Init the store.
|
||||
*
|
||||
* @param {Array} users The users in the system. Empty array if current user is not an admin.
|
||||
* @param {Object} currentUser The current user.
|
||||
* @param {Array.<Object>} users The users in the system. Empty array if current user is not an admin.
|
||||
* @param {Object} currentUser The current user.
|
||||
*/
|
||||
init(users, currentUser) {
|
||||
this.state.users = users;
|
||||
|
@ -33,7 +33,7 @@ export default {
|
|||
/**
|
||||
* Get all users.
|
||||
*
|
||||
* @return {Array}
|
||||
* @return {Array.<Object>}
|
||||
*/
|
||||
all() {
|
||||
return this.state.users;
|
||||
|
@ -42,7 +42,7 @@ export default {
|
|||
/**
|
||||
* Get a user by his ID
|
||||
*
|
||||
* @param {integer} id
|
||||
* @param {Integer} id
|
||||
*
|
||||
* @return {Object}
|
||||
*/
|
||||
|
@ -81,8 +81,8 @@ export default {
|
|||
/**
|
||||
* Log a user in.
|
||||
*
|
||||
* @param {string} email
|
||||
* @param {string} password
|
||||
* @param {String} email
|
||||
* @param {String} password
|
||||
* @param {?Function} successCb
|
||||
* @param {?Function} errorCb
|
||||
*/
|
||||
|
@ -137,9 +137,9 @@ export default {
|
|||
* Update a user's profile.
|
||||
*
|
||||
* @param {Object} user
|
||||
* @param {string} name
|
||||
* @param {email} email
|
||||
* @param {password} password
|
||||
* @param {String} name
|
||||
* @param {String} email
|
||||
* @param {String} password
|
||||
* @param {?Function} cb
|
||||
*/
|
||||
update(user, name, email, password, cb = null) {
|
||||
|
|
Loading…
Reference in a new issue