Mirrors/koel
2
0
Fork 0
mirror of https://github.com/koel/koel synced 2024-11-24 21:23:06 +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).
*
* @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);

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)
* 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) {

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)
* 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) {

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

@ -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;

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)
* 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) {

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.
* @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) {

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

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

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

@ -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;

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

@ -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;

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.
*
* @type {Array}
* @type {Array.<Object>}
*/
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.
*
* @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);

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

@ -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.

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

@ -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);

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

@ -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.

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

@ -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.

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

@ -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);

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

@ -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
resources/assets/js/stores/song.js
View file

@ -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));

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

@ -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) {