Mirrors/koel
2
0
Fork 0
mirror of https://github.com/koel/koel synced 2024-11-28 15:00:42 +00:00
Code Issues Projects Releases Packages Wiki Activity

Better jsdoc

Browse source
This commit is contained in:
An Phan 2016-01-17 22:26:24 +08:00
parent d32fda6342
commit c017a8dab6
20 changed files with 90 additions and 73 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

4
resources/assets/js/app.vue
View file

@ -170,8 +170,8 @@
/** /**
* Load (display) a main panel (view). * Load (display) a main panel (view).
* *
* @param string view The view, which can be found under components/main-wrapper/main-content. * @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 {...*} Extra data to attach to the view.
*/ */
loadMainView(view, ...args) { loadMainView(view, ...args) {
this.$broadcast('main-content-view:load', view, ...args); this.$broadcast('main-content-view:load', view, ...args);

2
resources/assets/js/components/main-wrapper/main-content/album.vue
View file

@ -62,7 +62,7 @@
* Listen to 'main-content-view:load' event (triggered from $root currently) * Listen to 'main-content-view:load' event (triggered from $root currently)
* to load the requested album into view if applicable. * 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 * @param {Object} album The album object
*/ */
'main-content-view:load': function (view, album) { 'main-content-view:load': function (view, album) {

2
resources/assets/js/components/main-wrapper/main-content/artist.vue
View file

@ -62,7 +62,7 @@
* Listen to 'main-content-view:load' event (triggered from $root currently) * Listen to 'main-content-view:load' event (triggered from $root currently)
* to load the requested artist into view if applicable. * 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 * @param {Object} artist
*/ */
'main-content-view:load': function (view, artist) { 'main-content-view:load': function (view, artist) {

2
resources/assets/js/components/main-wrapper/main-content/index.vue
View file

@ -52,7 +52,7 @@
* *
* @param {Object} song * @param {Object} song
* *
* @return {boolean} * @return {Boolean}
*/ */
'song:played': function (song) { 'song:played': function (song) {
this.albumCover = song.album.cover === albumStore.stub.cover ? null : song.album.cover; this.albumCover = song.album.cover === albumStore.stub.cover ? null : song.album.cover;

2
resources/assets/js/components/main-wrapper/main-content/playlist.vue
View file

@ -76,7 +76,7 @@
* Listen to 'main-content-view:load' event (triggered from $root currently) * Listen to 'main-content-view:load' event (triggered from $root currently)
* to load the requested playlist into view if applicable. * 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 * @param {Object} playlist
*/ */
'main-content-view:load': function (view, playlist) { 'main-content-view:load': function (view, playlist) {

6
resources/assets/js/components/main-wrapper/main-content/users.vue
View file

@ -136,9 +136,9 @@
/** /**
* Cancel editing, or simply close the form after updating. * Cancel editing, or simply close the form after updating.
* @param {boolean=true} rollback If true, editing was cancelled. * @param {Boolean=true} rollback If true, editing was cancelled.
* The original state of the edited user must be restored. * The original state of the edited user must be restored.
* If false, editing was successfully committed. * If false, editing was successfully committed.
*/ */
cancelEdit(rollback = true) { cancelEdit(rollback = true) {
if (rollback) { if (rollback) {

2
resources/assets/js/components/main-wrapper/sidebar/index.vue
View file

@ -103,7 +103,7 @@
* *
* @param {Object} e The event * @param {Object} e The event
* *
* @return {boolean} * @return {Boolean}
*/ */
handleDrop(e) { handleDrop(e) {
this.removeDroppableState(e); this.removeDroppableState(e);

2
resources/assets/js/components/main-wrapper/sidebar/playlist-item.vue
View file

@ -125,7 +125,7 @@
* *
* @param {Object} e The event * @param {Object} e The event
* *
* @return {boolean} * @return {Boolean}
*/ */
handleDrop(e) { handleDrop(e) {
this.removeDroppableState(e); this.removeDroppableState(e);

2
resources/assets/js/components/site-footer/equalizer.vue
View file

@ -103,7 +103,7 @@
/** /**
* Init the equalizer. * Init the equalizer.
* *
* @param {Object} player The audio player DOM. * @param {Element} player The audio player's DOM.
*/ */
init(player) { init(player) {
var AudioContext = window.AudioContext || window.webkitAudioContext || false; var AudioContext = window.AudioContext || window.webkitAudioContext || false;

6
resources/assets/js/components/site-footer/index.vue
View file

@ -94,7 +94,7 @@
/** /**
* Indicate if we should build and use an equalizer. * Indicate if we should build and use an equalizer.
* *
* @type {boolean} * @type {Boolean}
*/ */
useEqualizer: utils.isAudioContextSupported(), useEqualizer: utils.isAudioContextSupported(),
}; };
@ -116,7 +116,7 @@
/** /**
* Get the album cover for the current song. * Get the album cover for the current song.
* *
* @return {?string} * @return {?String}
*/ */
cover() { cover() {
// don't display the default cover here // don't display the default cover here
@ -235,7 +235,7 @@
* *
* @param {Object} song * @param {Object} song
* *
* @return {boolean} * @return {Boolean}
*/ */
'song:played': function (song) { 'song:played': function (song) {
this.playing = true; this.playing = true;

2
resources/assets/js/mixins/has-song-list.js
View file

@ -23,7 +23,7 @@ export default {
/** /**
* An array of selected songs in the list. * An array of selected songs in the list.
* *
* @type {Array} * @type {Array.<Object>}
*/ */
selectedSongs: [], selectedSongs: [],

18
resources/assets/js/services/playback.js
View file

@ -19,7 +19,7 @@ export default {
/** /**
* Initialize the playback service for this whole Koel app. * 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) { init(app) {
// We don't need to init this service twice, or the media events will be duplicated. // 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. * 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. * If we're in REPEAT_ALL mode and there's no next song, just get the first song.
*
* @return {Object} The song
*/ */
nextSong() { nextSong() {
var next = queueStore.getNextSong(); var next = queueStore.getNextSong();
@ -148,6 +150,8 @@ export default {
/** /**
* Get the prev song in the queue. * Get the prev song in the queue.
* If we're in REPEAT_ALL mode and there's no prev song, get the last song. * If we're in REPEAT_ALL mode and there's no prev song, get the last song.
*
* @return {Object} The song
*/ */
prevSong() { prevSong() {
var prev = queueStore.getPrevSong(); var prev = queueStore.getPrevSong();
@ -219,8 +223,8 @@ export default {
/** /**
* Set the volume level. * Set the volume level.
* *
* @param {integer} volume 0-10 * @param {Number} volume 0-10
* @param {boolean=true} persist Whether the volume should be saved into local storage * @param {Boolean=true} persist Whether the volume should be saved into local storage
*/ */
setVolume(volume, persist = true) { setVolume(volume, persist = true) {
this.player.setVolume(volume); this.player.setVolume(volume);
@ -281,8 +285,8 @@ export default {
/** /**
* Queue up songs (replace them into the queue) and start playing right away. * 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 {?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. * @param {Boolean=false} shuffle Whether to shuffle the songs before playing.
*/ */
queueAndPlay(songs = null, shuffle = false) { queueAndPlay(songs = null, shuffle = false) {
if (!songs) { if (!songs) {
@ -324,7 +328,7 @@ export default {
* Play all songs by an artist. * Play all songs by an artist.
* *
* @param {Object} artist The artist object * @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) { playAllByArtist(artist, shuffle = true) {
this.queueAndPlay(artistStore.getSongsByArtist(artist), true); this.queueAndPlay(artistStore.getSongsByArtist(artist), true);
@ -334,7 +338,7 @@ export default {
* Play all songs in an album. * Play all songs in an album.
* *
* @param {Object} album The album object * @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) { playAllInAlbum(album, shuffle = true) {
this.queueAndPlay(album.songs, true); this.queueAndPlay(album.songs, true);

4
resources/assets/js/services/utils.js
View file

@ -34,7 +34,7 @@ export default {
* *
* @param {Object} error The error object in JSON format. * @param {Object} error The error object in JSON format.
* *
* @return {Array} * @return {Array.<String>}
*/ */
parseValidationError(error) { parseValidationError(error) {
return Object.keys(error).reduce((messages, field) => messages.concat(error[field]), []); 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. * Check if AudioContext is supported by the current browser.
* *
* @return {boolean} * @return {Boolean}
*/ */
isAudioContextSupported() { isAudioContextSupported() {
// Apple device just doesn't love AudioContext that much. // Apple device just doesn't love AudioContext that much.

9
resources/assets/js/stores/album.js
View file

@ -14,7 +14,7 @@ export default {
/** /**
* Init the store. * 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) { init(artists) {
// Traverse through the artists array and add their albums into our master album list. // 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); songStore.init(this.state.albums);
}, },
/**
* Get all albums in the store.
*
* @return {Array.<Object>}
*/
all() { all() {
return this.state.albums; return this.state.albums;
}, },
@ -43,7 +48,7 @@ export default {
* *
* @param {Object} album * @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) { getLength(album) {
album.length = _.reduce(album.songs, (length, song) => length + song.length, 0); album.length = _.reduce(album.songs, (length, song) => length + song.length, 0);

6
resources/assets/js/stores/artist.js
View file

@ -14,7 +14,7 @@ export default {
/** /**
* Init the store. * 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) { init(artists) {
this.state.artists = artists; this.state.artists = artists;
@ -38,7 +38,7 @@ export default {
* *
* @param {Object} artist * @param {Object} artist
* *
* @return {Array} * @return {Array.<Object>}
*/ */
getSongsByArtist(artist) { getSongsByArtist(artist) {
if (!artist.songs) { if (!artist.songs) {
@ -53,7 +53,7 @@ export default {
* *
* @param {Object} artist * @param {Object} artist
* *
* @return {string} * @return {String}
*/ */
getImage(artist) { getImage(artist) {
// If the artist already has a proper image, just return it. // If the artist already has a proper image, just return it.

13
resources/assets/js/stores/favorite.js
View file

@ -10,6 +10,11 @@ export default {
fmtLength: '', fmtLength: '',
}, },
/**
* Get all songs favorited by the current user.
*
* @return {Array.<Object>}
*/
all() { all() {
return this.state.songs; return this.state.songs;
}, },
@ -64,8 +69,8 @@ export default {
/** /**
* Like a bunch of songs. * Like a bunch of songs.
* *
* @param {Array} songs * @param {Array.<Object>} songs
* @param {?Function} cb * @param {?Function} cb
*/ */
like(songs, cb = null) { like(songs, cb = null) {
// Don't wait for the HTTP response to update the status, just set them to Liked right away. // 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. * Unlike a bunch of songs.
* *
* @param {Array} songs * @param {Array.<Object>} songs
* @param {?Function} cb * @param {?Function} cb
*/ */
unlike(songs, cb = null) { unlike(songs, cb = null) {
// Don't wait for the HTTP response to update the status, just set them to Unliked right away. // Don't wait for the HTTP response to update the status, just set them to Unliked right away.

25
resources/assets/js/stores/playlist.js
View file

@ -17,6 +17,11 @@ export default {
_.each(this.state.playlists, this.getSongs); _.each(this.state.playlists, this.getSongs);
}, },
/**
* Get all playlists of the current user.
*
* @return {Array.<Object>}
*/
all() { all() {
return this.state.playlists; return this.state.playlists;
}, },
@ -24,7 +29,7 @@ export default {
/** /**
* Get all songs in a playlist. * Get all songs in a playlist.
* *
* return {Array} * return {Array.<Object>}
*/ */
getSongs(playlist) { getSongs(playlist) {
return (playlist.songs = songStore.byIds(playlist.songs)); return (playlist.songs = songStore.byIds(playlist.songs));
@ -33,9 +38,9 @@ export default {
/** /**
* Create a new playlist, optionally with its songs. * Create a new playlist, optionally with its songs.
* *
* @param {string} name Name of the playlist * @param {String} name Name of the playlist
* @param {Array} songs An array of song objects * @param {Array.<Object>} songs An array of song objects
* @param {?Function} cb * @param {?Function} cb
*/ */
store(name, songs, cb = null) { store(name, songs, cb = null) {
if (songs.length) { if (songs.length) {
@ -74,9 +79,9 @@ export default {
/** /**
* Add songs into a playlist. * Add songs into a playlist.
* *
* @param {Object} playlist * @param {Object} playlist
* @param {Array} songs * @param {Array.<Object>} songs
* @param {?Function} cb * @param {?Function} cb
*/ */
addSongs(playlist, songs, cb = null) { addSongs(playlist, songs, cb = null) {
var count = playlist.songs.length; var count = playlist.songs.length;
@ -96,9 +101,9 @@ export default {
/** /**
* Remove songs from a playlist. * Remove songs from a playlist.
* *
* @param {Object} playlist * @param {Object} playlist
* @param {Array} songs * @param {Array.<Object>} songs
* @param {?Function} cb * @param {?Function} cb
*/ */
removeSongs(playlist, songs, cb = null) { removeSongs(playlist, songs, cb = null) {
playlist.songs = _.difference(playlist.songs, songs); playlist.songs = _.difference(playlist.songs, songs);

20
resources/assets/js/stores/queue.js
View file

@ -31,8 +31,6 @@ export default {
// It's alright // It's alright
// Take anything you want from me // Take anything you want from me
// Anything... // Anything...
//
// [CRAZY SOLO BITCH!]
}, },
all() { all() {
@ -52,7 +50,7 @@ export default {
* *
* @param {Object} song * @param {Object} song
* *
* @return {boolean} * @return {Boolean}
*/ */
contains(song) { contains(song) {
return _.includes(this.all(), song); return _.includes(this.all(), song);
@ -62,9 +60,9 @@ export default {
* Add a list of songs to the end of the current queue, * Add a list of songs to the end of the current queue,
* or replace the current queue as a whole if `replace` is true. * or replace the current queue as a whole if `replace` is true.
* *
* @param {Object|Array} songs The song, or an array of songs * @param {Object|Array.<Object>} songs The song, or an array of songs
* @param {boolean} replace Whether to replace the current queue * @param {Boolean} replace Whether to replace the current queue
* @param {boolean} toTop Whether to prepend of append to the queue * @param {Boolean} toTop Whether to prepend of append to the queue
*/ */
queue(songs, replace = false, toTop = false) { queue(songs, replace = false, toTop = false) {
if (!Array.isArray(songs)) { if (!Array.isArray(songs)) {
@ -85,7 +83,7 @@ export default {
/** /**
* Queue song(s) to after the current song. * Queue song(s) to after the current song.
* *
* @param {Array|Object} songs * @param {Array.<Object>|Object} songs
*/ */
queueAfterCurrent(songs) { queueAfterCurrent(songs) {
if (!Array.isArray(songs)) { if (!Array.isArray(songs)) {
@ -103,7 +101,7 @@ export default {
/** /**
* Unqueue a song, or several songs at once. * 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) { unqueue(songs) {
if (!Array.isArray(songs)) { if (!Array.isArray(songs)) {
@ -116,8 +114,8 @@ export default {
/** /**
* Move some songs to after a target. * Move some songs to after a target.
* *
* @param {Array} songs Songs to move * @param {Array.<Object>} songs Songs to move
* @param {Object} target The target song object * @param {Object} target The target song object
*/ */
move(songs, target) { move(songs, target) {
var $targetIndex = this.indexOf(target); var $targetIndex = this.indexOf(target);
@ -145,7 +143,7 @@ export default {
* *
* @param {Object} song * @param {Object} song
* *
* @return {?integer} * @return {?Integer}
*/ */
indexOf(song) { indexOf(song) {
return _.indexOf(this.state.songs, song); return _.indexOf(this.state.songs, song);

18
resources/assets/js/stores/song.js
View file

@ -18,7 +18,7 @@ export default {
/** /**
* Init the store. * 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) { init(albums) {
// Iterate through the albums. With each, add its songs into our master song list. // 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. * 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) { initInteractions(interactions) {
favoriteStore.clear(); favoriteStore.clear();
@ -65,10 +65,10 @@ export default {
/** /**
* Get the total duration of some songs. * Get the total duration of some songs.
* *
* @param {Array} songs * @param {Array.<Object>} songs
* @param {boolean} toHis Wheter to convert the duration into H:i:s format * @param {Boolean} toHis Wheter to convert the duration into H:i:s format
* *
* @return {float|string} * @return {Float|String}
*/ */
getLength(songs, toHis) { getLength(songs, toHis) {
var duration = _.reduce(songs, (length, song) => length + song.length, 0); var duration = _.reduce(songs, (length, song) => length + song.length, 0);
@ -83,7 +83,7 @@ export default {
/** /**
* Get all songs. * Get all songs.
* *
* @return {Array} * @return {Array.<Object>}
*/ */
all() { all() {
return this.state.songs; return this.state.songs;
@ -92,7 +92,7 @@ export default {
/** /**
* Get a song by its ID. * Get a song by its ID.
* *
* @param {string} id * @param {String} id
* *
* @return {Object} * @return {Object}
*/ */
@ -103,9 +103,9 @@ export default {
/** /**
* Get songs by their IDs. * Get songs by their IDs.
* *
* @param {Array} ids * @param {Array.<String>} ids
* *
* @return {Array} * @return {Array.<Object>}
*/ */
byIds(ids) { byIds(ids) {
return _.map(ids, id => this.byId(id)); return _.map(ids, id => this.byId(id));

18
resources/assets/js/stores/user.js
View file

@ -16,8 +16,8 @@ export default {
/** /**
* Init the store. * Init the store.
* *
* @param {Array} users The users in the system. Empty array if current user is not an admin. * @param {Array.<Object>} users The users in the system. Empty array if current user is not an admin.
* @param {Object} currentUser The current user. * @param {Object} currentUser The current user.
*/ */
init(users, currentUser) { init(users, currentUser) {
this.state.users = users; this.state.users = users;
@ -33,7 +33,7 @@ export default {
/** /**
* Get all users. * Get all users.
* *
* @return {Array} * @return {Array.<Object>}
*/ */
all() { all() {
return this.state.users; return this.state.users;
@ -42,7 +42,7 @@ export default {
/** /**
* Get a user by his ID * Get a user by his ID
* *
* @param {integer} id * @param {Integer} id
* *
* @return {Object} * @return {Object}
*/ */
@ -81,8 +81,8 @@ export default {
/** /**
* Log a user in. * Log a user in.
* *
* @param {string} email * @param {String} email
* @param {string} password * @param {String} password
* @param {?Function} successCb * @param {?Function} successCb
* @param {?Function} errorCb * @param {?Function} errorCb
*/ */
@ -137,9 +137,9 @@ export default {
* Update a user's profile. * Update a user's profile.
* *
* @param {Object} user * @param {Object} user
* @param {string} name * @param {String} name
* @param {email} email * @param {String} email
* @param {password} password * @param {String} password
* @param {?Function} cb * @param {?Function} cb
*/ */
update(user, name, email, password, cb = null) { update(user, name, email, password, cb = null) {