From 223b7323a391ad6b0c240c079cc714fc1b257440 Mon Sep 17 00:00:00 2001
From: kunkka <hawtimzhang@gmail.com>
Date: Sun, 25 Oct 2020 13:55:19 +0800
Subject: [PATCH] feat: update api comments with jsdoc.

---
 src/api/album.js    |  1 +
 src/api/artist.js   | 40 +++++++++++++++++------
 src/api/auth.js     | 41 +++++++++++++++++-------
 src/api/mv.js       | 26 +++++++++++++--
 src/api/others.js   | 15 +++++++++
 src/api/playlist.js | 78 ++++++++++++++++++++++++++++++++++++---------
 src/api/track.js    |  2 +-
 src/api/user.js     | 39 +++++++++++++----------
 8 files changed, 186 insertions(+), 56 deletions(-)

diff --git a/src/api/album.js b/src/api/album.js
index 28f540b..214128e 100644
--- a/src/api/album.js
+++ b/src/api/album.js
@@ -18,6 +18,7 @@ export function getAlbum(id) {
     return data;
   });
 }
+
 /**
  * 全部新碟
  * 说明 : 登录后调用此接口 ,可获取全部新碟
diff --git a/src/api/artist.js b/src/api/artist.js
index 259dadf..0a5ed88 100644
--- a/src/api/artist.js
+++ b/src/api/artist.js
@@ -1,6 +1,11 @@
 import request from "@/utils/request";
 import { mapTrackPlayableStatus } from "@/utils/common";
 
+/**
+ * 获取歌手单曲
+ * 说明 : 调用此接口 , 传入歌手 id, 可获得歌手部分信息和热门歌曲
+ * @param {number} id - 歌手 id, 可由搜索接口获得
+ */
 export function getArtist(id) {
   return request({
     url: "/artists",
@@ -14,10 +19,18 @@ export function getArtist(id) {
   });
 }
 
+/**
+ * 获取歌手专辑
+ * 说明 : 调用此接口 , 传入歌手 id, 可获得歌手专辑内容
+ * - id: 歌手 id
+ * - limit: 取出数量 , 默认为 50
+ * - offset: 偏移数量 , 用于分页 , 如 :( 页数 -1)*50, 其中 50 为 limit 的值 , 默认为 0
+ * @param {Object} params
+ * @param {number} params.id
+ * @param {number=} params.limit
+ * @param {number=} params.offset
+ */
 export function getArtistAlbum(params) {
-  // 必选参数 : id: 歌手 id
-  // 可选参数 : limit: 取出数量 , 默认为 50
-  // offset: 偏移数量 , 用于分页 , 如 :( 页数 -1)*50, 其中 50 为 limit 的值 , 默认 为 0
   return request({
     url: "/artist/album",
     method: "get",
@@ -25,12 +38,17 @@ export function getArtistAlbum(params) {
   });
 }
 
+/**
+ * 歌手榜
+ * 说明 : 调用此接口 , 可获取排行榜中的歌手榜
+ * - type : 地区
+ * 1: 华语
+ * 2: 欧美
+ * 3: 韩国
+ * 4: 日本
+ * @param {number=} type
+ */
 export function toplistOfArtists(type = null) {
-  // type : 地区
-  // 1: 华语
-  // 2: 欧美
-  // 3: 韩国
-  // 4: 日本
   return request({
     url: "/toplist/artist",
     method: "get",
@@ -39,7 +57,11 @@ export function toplistOfArtists(type = null) {
     },
   });
 }
-
+/**
+ * 获取歌手 mv
+ * 说明 : 调用此接口 , 传入歌手 id, 可获得歌手 mv 信息 , 具体 mv 播放地址可调 用/mv传入此接口获得的 mvid 来拿到 , 如 : /artist/mv?id=6452,/mv?mvid=5461064
+ * @param {number} id 歌手 id, 可由搜索接口获得
+ */
 export function artistMv(id) {
   return request({
     url: "/artist/mv",
diff --git a/src/api/auth.js b/src/api/auth.js
index da40e6a..700bb4a 100644
--- a/src/api/auth.js
+++ b/src/api/auth.js
@@ -1,25 +1,33 @@
 import request from "@/utils/request";
 
+/**
+ * 手机登录
+ * - phone: 手机号码
+ * - password: 密码
+ * - countrycode: 国家码，用于国外手机号登录，例如美国传入：1
+ * @param {Object} params
+ * @param {string} params.phone
+ * @param {string} params.password
+ * @param {string=} params.countrycode
+ */
 export function loginWithPhone(params) {
-  //必选参数 :
-  // phone: 手机号码
-  // password: 密码
-  // 可选参数 :
-  // countrycode: 国家码，用于国外手机号登录，例如美国传入：1
-  // md5_password: md5加密后的密码,传入后 password 将失效
   return request({
     url: "/login/cellphone",
     method: "post",
     params,
   });
 }
-
+/**
+ * 邮箱登录
+ * - email: 163 网易邮箱
+ * - password: 密码
+ * - md5_password: md5加密后的密码,传入后 password 将失效
+ * @param {Object} params
+ * @param {string} params.email
+ * @param {string} params.password
+ * @param {string=} params.md5_password
+ */
 export function loginWithEmail(params) {
-  // 必选参数 :
-  // email: 163 网易邮箱
-  // password: 密码
-  // 可选参数 :
-  // md5_password: md5加密后的密码,传入后 password 将失效
   return request({
     url: "/login",
     method: "post",
@@ -27,6 +35,11 @@ export function loginWithEmail(params) {
   });
 }
 
+/**
+ * 刷新登录
+ * 说明 : 调用此接口 , 可刷新登录状态
+ * - 调用例子 : /login/refresh
+ */
 export function loginRefresh() {
   return request({
     url: "/login/refresh",
@@ -34,6 +47,10 @@ export function loginRefresh() {
   });
 }
 
+/**
+ * 退出登录
+ * 说明 : 调用此接口 , 可退出登录
+ */
 export function logout() {
   return request({
     url: "/logout",
diff --git a/src/api/mv.js b/src/api/mv.js
index b114afc..d00b095 100644
--- a/src/api/mv.js
+++ b/src/api/mv.js
@@ -1,5 +1,12 @@
 import request from "@/utils/request";
 
+/**
+ * 获取 mv 数据
+ * 说明 : 调用此接口 , 传入 mvid ( 在搜索音乐的时候传 type=1004 获得 ) , 可获取对应 MV 数据 , 数据包含 mv 名字 , 歌手 , 发布时间 , mv 视频地址等数据 ,
+ * 其中 mv 视频 网易做了防盗链处理 , 可能不能直接播放 , 需要播放的话需要调用 ' mv 地址' 接口
+ * - 调用例子 : /mv/detail?mvid=5436712
+ * @param {number} mvid mv 的 id
+ */
 export function mvDetail(mvid) {
   return request({
     url: "/mv/detail",
@@ -10,16 +17,29 @@ export function mvDetail(mvid) {
   });
 }
 
+/**
+ * mv 地址
+ * 说明 : 调用此接口 , 传入 mv id,可获取 mv 播放地址
+ * - id: mv id
+ * - r: 分辨率,默认1080,可从 /mv/detail 接口获取分辨率列表
+ * - 调用例子 : /mv/url?id=5436712 /mv/url?id=10896407&r=1080
+ * @param {Object} params
+ * @param {number} params.id
+ * @param {number=} params.r
+ */
+
 export function mvUrl(params) {
-  // 必选参数 : id: mv id
-  // 可选参数 : r: 分辨率,默认1080,可从 /mv/detail 接口获取分辨率列表
   return request({
     url: "/mv/url",
     method: "get",
     params,
   });
 }
-
+/**
+ * 相似 mv
+ * 说明 : 调用此接口 , 传入 mvid 可获取相似 mv
+ * @param {number} mvid
+ */
 export function simiMv(mvid) {
   return request({
     url: "/simi/mv",
diff --git a/src/api/others.js b/src/api/others.js
index 0582e9e..f63423a 100644
--- a/src/api/others.js
+++ b/src/api/others.js
@@ -1,6 +1,21 @@
 import request from "@/utils/request";
 import { mapTrackPlayableStatus } from "@/utils/common";
 
+/**
+ * 搜索
+ * 说明 : 调用此接口 , 传入搜索关键词可以搜索该音乐 / 专辑 / 歌手 / 歌单 / 用户 , 关键词可以多个 , 以空格隔开 ,
+ * 如 " 周杰伦 搁浅 "( 不需要登录 ), 搜索获取的 mp3url 不能直接用 , 可通过 /song/url 接口传入歌曲 id 获取具体的播放链接
+ * - keywords : 关键词
+ * - limit : 返回数量 , 默认为 30
+ * - offset : 偏移数量，用于分页 , 如 : 如 :( 页数 -1)*30, 其中 30 为 limit 的值 , 默认为 0
+ * - type: 搜索类型；默认为 1 即单曲 , 取值意义 : 1: 单曲, 10: 专辑, 100: 歌手, 1000: 歌单, 1002: 用户, 1004: MV, 1006: 歌词, 1009: 电台, 1014: 视频, 1018:综合
+ * - 调用例子 : /search?keywords=海阔天空 /cloudsearch?keywords=海阔天空(更全)
+ * @param {Object} params
+ * @param {string} params.keywords
+ * @param {number=} params.limit
+ * @param {number=} params.offset
+ * @param {number=} params.type
+ */
 export function search(params) {
   return request({
     url: "/search",
diff --git a/src/api/playlist.js b/src/api/playlist.js
index 584675d..d643b50 100644
--- a/src/api/playlist.js
+++ b/src/api/playlist.js
@@ -1,23 +1,44 @@
 import request from "@/utils/request";
 import { mapTrackPlayableStatus } from "@/utils/common";
 
+/**
+ * 推荐歌单
+ * 说明 : 调用此接口 , 可获取推荐歌单
+ * - limit: 取出数量 , 默认为 30 (不支持 offset)
+ * - 调用例子 : /personalized?limit=1
+ * @param {Object} params
+ * @param {number=} params.limit
+ */
 export function recommendPlaylist(params) {
-  // limit: 取出数量 , 默认为 30
   return request({
     url: "/personalized",
     method: "get",
     params,
   });
 }
+/**
+ * 获取每日推荐歌单
+ * 说明 : 调用此接口 , 可获得每日推荐歌单 ( 需要登录 )
+ * @param {Object} params
+ * @param {number=} params.limit
+ */
 export function dailyRecommendPlaylist(params) {
-  // limit: 取出数量 , 默认为 30
   return request({
     url: "/recommend/resource",
     method: "get",
     params,
   });
 }
-
+/**
+ * 获取歌单详情
+ * 说明 : 歌单能看到歌单名字, 但看不到具体歌单内容 , 调用此接口 , 传入歌单 id, 可以获取对应歌单内的所有的音乐(未登录状态只能获取不完整的歌单,登录后是完整的)，
+ * 但是返回的trackIds是完整的，tracks 则是不完整的，可拿全部 trackIds 请求一次 song/detail 接口
+ * 获取所有歌曲的详情 (https://github.com/Binaryify/NeteaseCloudMusicApi/issues/452)
+ * - id : 歌单 id
+ * - s : 歌单最近的 s 个收藏者, 默认为8
+ * @param {number} id
+ * @param {boolean=} noCache
+ */
 export function getPlaylistDetail(id, noCache = false) {
   let params = { id };
   if (noCache) params.timestamp = new Date().getTime();
@@ -30,11 +51,18 @@ export function getPlaylistDetail(id, noCache = false) {
     return data;
   });
 }
-
+/**
+ * 获取精品歌单
+ * 说明 : 调用此接口 , 可获取精品歌单
+ * - cat: tag, 比如 " 华语 "、" 古风 " 、" 欧美 "、" 流行 ", 默认为 "全部", 可从精品歌单标签列表接口获取(/playlist/highquality/tags)
+ * - limit: 取出歌单数量 , 默认为 20
+ * - before: 分页参数,取上一页最后一个歌单的 updateTime 获取下一页数据
+ * @param {Object} params
+ * @param {string} params.cat
+ * @param {number=} params.limit
+ * @param {number} params.before
+ */
 export function highQualityPlaylist(params) {
-  // 可选参数: cat: tag, 比如 " 华语 "、" 古风 " 、" 欧美 "、" 流行 ", 默认为 "全部", 可从精品歌单标签列表接口获取(/playlist/highquality / tags)
-  // limit: 取出歌单数量 , 默认为 20
-  // before: 分页参数,取上一页最后一个歌单的 updateTime 获取下一页数据
   return request({
     url: "/top/playlist/highquality",
     method: "get",
@@ -42,11 +70,18 @@ export function highQualityPlaylist(params) {
   });
 }
 
+/**
+ * 歌单 ( 网友精选碟 )
+ * 说明 : 调用此接口 , 可获取网友精选碟歌单
+ * - order: 可选值为 'new' 和 'hot', 分别对应最新和最热 , 默认为 'hot'
+ * - cat: tag, 比如 " 华语 "、" 古风 " 、" 欧美 "、" 流行 ", 默认为 "全部",可从歌单分类接口获取(/playlist/catlist)
+ * - limit: 取出歌单数量 , 默认为 50
+ * @param {Object} params
+ * @param {string} params.order
+ * @param {string} params.cat
+ * @param {number=} params.limit
+ */
 export function topPlaylist(params) {
-  //  可选参数 : order: 可选值为 'new' 和 'hot', 分别对应最新和最热 , 默认为 'hot'
-  // cat:cat: tag, 比如 " 华语 "、" 古风 " 、" 欧美 "、" 流行 ", 默认为 "全部",可从歌单分类接口获取(/playlist/catlist)
-  // limit: 取出歌单数量 , 默认为 50
-  // offset: 偏移数量 , 用于分页 , 如 :( 评论页数 -1)*50, 其中 50 为 limit 的值
   return request({
     url: "/top/playlist",
     method: "get",
@@ -54,23 +89,36 @@ export function topPlaylist(params) {
   });
 }
 
+/**
+ * 歌单分类
+ * 说明 : 调用此接口,可获取歌单分类,包含 category 信息
+ */
 export function playlistCatlist() {
   return request({
     url: "/playlist/catlist",
     method: "get",
   });
 }
-
+/**
+ * 所有榜单
+ * 说明 : 调用此接口,可获取所有榜单 接口地址 : /toplist
+ */
 export function toplists() {
   return request({
     url: "/toplist",
     method: "get",
   });
 }
-
+/**
+ * 收藏/取消收藏歌单
+ * 说明 : 调用此接口, 传入类型和歌单 id 可收藏歌单或者取消收藏歌单
+ * - t : 类型,1:收藏,2:取消收藏
+ * - id : 歌单 id
+ * @param {Object} params
+ * @param {number} params.t
+ * @param {number} params.id
+ */
 export function subscribePlaylist(params) {
-  // 必选参数 :
-  // t : 类型,1:收藏,2:取消收藏 id : 歌单 id
   return request({
     url: "/playlist/subscribe",
     method: "get",
diff --git a/src/api/track.js b/src/api/track.js
index 1b50eea..11876c7 100644
--- a/src/api/track.js
+++ b/src/api/track.js
@@ -94,7 +94,7 @@ export function likeATrack(params) {
  * @param {Object} params
  * @param {number} params.id
  * @param {number} params.sourceid
- * @param {number=} [params.time]
+ * @param {number=} params.time
  */
 export function scrobble(params) {
   params.timestamp = new Date().getTime();
diff --git a/src/api/user.js b/src/api/user.js
index edabc43..d2e4aa5 100644
--- a/src/api/user.js
+++ b/src/api/user.js
@@ -1,19 +1,11 @@
 import request from "@/utils/request";
 
-export function login(params) {
-  //     必选参数 :
-  // phone: 手机号码
-  // password: 密码
-  // 可选参数 :
-  // countrycode: 国家码，用于国外手机号登陆，例如美国传入：1
-  // md5_password: md5加密后的密码,传入后 password 将失效
-  return request({
-    url: "/login/cellphone",
-    method: "get",
-    params,
-  });
-}
-
+/**
+ * 获取用户详情
+ * 说明 : 登录后调用此接口 , 传入用户 id, 可以获取用户详情
+ * - uid : 用户 id
+ * @param {number} uid
+ */
 export function userDetail(uid) {
   return request({
     url: "/user/detail",
@@ -24,9 +16,18 @@ export function userDetail(uid) {
   });
 }
 
+/**
+ * 获取用户歌单
+ * 说明 : 登录后调用此接口 , 传入用户 id, 可以获取用户歌单
+ * - uid : 用户 id
+ * - limit : 返回数量 , 默认为 30
+ * - offset : 偏移数量，用于分页 , 如 :( 页数 -1)*30, 其中 30 为 limit 的值 , 默认为 0
+ * @param {Object} params
+ * @param {number} params.uid
+ * @param {number} params.limit
+ * @param {number=} params.offset
+ */
 export function userPlaylist(params) {
-  // limit : 返回数量 , 默认为 30
-  // offset : 偏移数量，用于分页 , 如 :( 页数 -1)*30, 其中 30 为 limit 的值 , 默认为 0
   return request({
     url: "/user/playlist",
     method: "get",
@@ -34,6 +35,12 @@ export function userPlaylist(params) {
   });
 }
 
+/**
+ * 喜欢音乐列表
+ * 说明 : 调用此接口 , 传入用户 id, 可获取已喜欢音乐id列表(id数组)
+ * - uid: 用户 id
+ * @param {number} uid
+ */
 export function userLikedSongsIDs(uid) {
   return request({
     url: "/likelist",