From 61bb636f176d115158a355e8cd16cb87c43ac431 Mon Sep 17 00:00:00 2001
From: Hawtim Zhang <hawtimzhang@gmail.com>
Date: Sat, 24 Oct 2020 11:41:15 +0800
Subject: [PATCH] feat: using jsdoc config to update api comments (#49)

* feat: add config to resolve path alias.

* feat: use vue-i18n for language switch

* feat: add .editorconfig for ide

* fix: add no-referrer to avoid CROB

* fix: setCookie and fix typo

* feat: integrate vue-i18n

* feat: player component i18n support

* fix: duplicate key warning in explore page

* fix: like songs number changed in library page

* fire: remove todo

* fix: same text search on enter will cause error

* fix: scrobble error params type

* feat: prettier task supported

* fix: prettier ignore config update

* fix: conflict

* fix: commitMP3 and countrycode to countryCode

* lint: prettier

* feat: settings page i18n supported

* feat: option for  change default devServer port

* feat: using jsdoc config to update api comments

* feat: update jsdoc comments

* docs: update jsdoc comments

* docs: update jsdoc comments
---
 src/api/album.js | 20 ++++++++++++----
 src/api/track.js | 62 ++++++++++++++++++++++++++++++++++--------------
 2 files changed, 60 insertions(+), 22 deletions(-)

diff --git a/src/api/album.js b/src/api/album.js
index 5149b03..28f540b 100644
--- a/src/api/album.js
+++ b/src/api/album.js
@@ -1,6 +1,11 @@
 import request from "@/utils/request";
 import { mapTrackPlayableStatus } from "@/utils/common";
 
+/**
+ * 获取专辑内容
+ * 说明 : 调用此接口 , 传入专辑 id, 可获得专辑内容
+ * @param {number} id
+ */
 export function getAlbum(id) {
   return request({
     url: "/album",
@@ -13,11 +18,18 @@ export function getAlbum(id) {
     return data;
   });
 }
-
+/**
+ * 全部新碟
+ * 说明 : 登录后调用此接口 ,可获取全部新碟
+ * - limit - 返回数量 , 默认为 30
+ * - offset - 偏移数量，用于分页 , 如 :( 页数 -1)*30, 其中 30 为 limit 的值 , 默认为 0
+ * - area - ALL:全部,ZH:华语,EA:欧美,KR:韩国,JP:日本
+ * @param {Object} params
+ * @param {number} params.limit
+ * @param {number=} params.offset
+ * @param {string} params.area
+ */
 export function newAlbums(params) {
-  // limit : 返回数量 , 默认为 30
-  // offset : 偏移数量，用于分页 , 如 :( 页数 -1)*30, 其中 30 为 limit 的值 , 默认为 0
-  // area : ALL:全部,ZH:华语,EA:欧美,KR:韩国,JP:日本
   return request({
     url: "/album/new",
     method: "get",
diff --git a/src/api/track.js b/src/api/track.js
index f3244fd..1fe0be9 100644
--- a/src/api/track.js
+++ b/src/api/track.js
@@ -1,7 +1,11 @@
+import store from "@/store";
 import request from "@/utils/request";
 import { mapTrackPlayableStatus } from "@/utils/common";
-import store from "@/store";
-
+/**
+ * 获取音乐 url
+ * 说明 : 使用歌单详情接口后 , 能得到的音乐的 id, 但不能得到的音乐 url, 调用此接口, 传入的音乐 id( 可多个 , 用逗号隔开 ), 可以获取对应的音乐的 url,未登录状态返回试听片段(返回字段包含被截取的正常歌曲的开始时间和结束时间)
+ * @param {string} id - 音乐的 id，例如 id=405998841,33894312
+ */
 export function getMP3(id) {
   let br =
     store.state.settings?.musicQuality !== undefined
@@ -16,37 +20,44 @@ export function getMP3(id) {
     },
   });
 }
-
-export function getTrackDetail(id) {
+/**
+ * 获取歌曲详情
+ * 说明 : 调用此接口 , 传入音乐 id(支持多个 id, 用 , 隔开), 可获得歌曲详情(注意:歌曲封面现在需要通过专辑内容接口获取)
+ * @param {string} ids - 音乐 id, 例如 ids=405998841,33894312
+ */
+export function getTrackDetail(ids) {
   return request({
     url: "/song/detail",
     method: "get",
     params: {
-      ids: id,
+      ids,
     },
   }).then((data) => {
     data.songs = mapTrackPlayableStatus(data.songs);
     return data;
   });
 }
+/**
+ * 获取歌词
+ * 说明 : 调用此接口 , 传入音乐 id 可获得对应音乐的歌词 ( 不需要登录 )
+ * @param {number} id - 音乐 id
+ */
 
 export function getLyric(id) {
   return request({
     url: "/lyric",
     method: "get",
     params: {
-      id: id,
+      id,
     },
   });
 }
-
+/**
+ * 新歌速递
+ * 说明 : 调用此接口 , 可获取新歌速递
+ * @param {number} type - 地区类型 id, 对应以下: 全部:0 华语:7 欧美:96 日本:8 韩国:16
+ */
 export function topSong(type) {
-  //   type: 地区类型 id,对应以下:
-  // 全部:0
-  // 华语:7
-  // 欧美:96
-  // 日本:8
-  // 韩国:16
   return request({
     url: "/top/song",
     method: "get",
@@ -55,10 +66,16 @@ export function topSong(type) {
     },
   });
 }
-
+/**
+ * 喜欢音乐
+ * 说明 : 调用此接口 , 传入音乐 id, 可喜欢该音乐
+ * - id - 歌曲 id
+ * - like - 默认为 true 即喜欢 , 若传 false, 则取消喜欢
+ * @param {Object} params
+ * @param {number} params.id
+ * @param {boolean=} [params.like]
+ */
 export function likeATrack(params) {
-  // 必选参数: id: 歌曲 id
-  // 可选参数 : like: 布尔值 , 默认为 true 即喜欢 , 若传 false, 则取消喜欢
   params.timestamp = new Date().getTime();
   return request({
     url: "/like",
@@ -67,9 +84,18 @@ export function likeATrack(params) {
   });
 }
 
+/**
+ * 听歌打卡
+ * 说明 : 调用此接口 , 传入音乐 id, 来源 id，歌曲时间 time，更新听歌排行数据
+ * - id - 歌曲 id
+ * - sourceid - 歌单或专辑 id
+ * - time - 歌曲播放时间,单位为秒
+ * @param {Object} params
+ * @param {number} params.id
+ * @param {number} params.sourceid
+ * @param {number=} [params.time]
+ */
 export function scrobble(params) {
-  // 必选参数 : id: 歌曲 id, sourceid: 歌单或专辑 id
-  // 可选参数 : time: 歌曲播放时间,单位为秒
   params.timestamp = new Date().getTime();
   return request({
     url: "/scrobble",