feat: 完善util的注释

Author: CC11001100

src/utils/code-util.js

@@ -1,9 +1,9 @@
 /**
+ * 获取函数的方法体代码。
  *
- * 获取函数的方法体代码
- *
- * @param fn
- * @return {string}
+ * @param {Function} fn - 要提取方法体的函数。
+ * @return {string} - 返回函数的方法体代码。
+ * @throws {TypeError} - 如果传入的参数不是函数，则抛出 TypeError。
  */
 function getFunctionBody(fn) {
     if (typeof fn !== 'function') {
@@ -22,10 +22,11 @@ function getFunctionBody(fn) {
 }
 
 /**
- * 获取函数的参数名
+ * 获取函数的参数名。
  *
- * @param fn
- * @return {string[]|*[]}
+ * @param {Function} fn - 要提取参数名的函数。
+ * @return {string[]} - 返回函数的参数名数组。如果没有参数，则返回空数组。
+ * @throws {TypeError} - 如果传入的参数不是函数，则抛出 TypeError。
  */
 function getParameterNames(fn) {
     if (typeof fn !== 'function') {
@@ -53,10 +54,10 @@ function getParameterNames(fn) {
 }
 
 /**
- * 生成一个随机的函数名
+ * 生成一个随机的函数名。
  *
- * @param length
- * @return {string}
+ * @param {number} [length=8] - 函数名的长度，默认为 8。
+ * @return {string} - 返回生成的随机函数名。
  */
 function generateRandomFunctionName(length = 8) {
     const chars = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ';
@@ -71,4 +72,4 @@ module.exports = {
     getFunctionBody,
     getParameterNames,
     generateRandomFunctionName,
-}
+};

src/utils/color-util.js

@@ -1,3 +1,8 @@
+/**
+ * 生成一个随机的 RGB 颜色值。
+ *
+ * @return {string} - 返回一个表示 RGB 颜色的字符串，格式为 `rgb(r, g, b)`，其中 `r`、`g`、`b` 分别是 0 到 255 之间的随机整数。
+ */
 function getRandomRGBColor() {
     const r = Math.floor(Math.random() * 256); // 红色分量 (0-255)
     const g = Math.floor(Math.random() * 256); // 绿色分量 (0-255)
@@ -7,4 +12,4 @@ function getRandomRGBColor() {
 
 module.exports = {
     getRandomRGBColor
-}
+};

src/utils/id-util.js

@@ -1,21 +1,19 @@
 /**
- * 生成一个随机id，类似UUID的格式
+ * 生成一个随机 ID，格式类似于 UUID。
  *
- * @returns {string}
+ * @returns {string} - 返回一个随机生成的 ID，格式为 "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx"。
  */
 function randomId() {
-    return 'xxxxxxxxxxxx4xxxyxxxxxxxxxxxxxxx'.replace(/[xy]/g, function (c) {
-        const r = Math.random() * 16 | 0,
-            v = c === 'x' ? r : (r & 0x3 | 0x8);
+    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, function (c) {
+        // 生成一个 0 到 15 的随机整数
+        const r = Math.random() * 16 | 0;
+        // 如果字符是 'x'，则直接使用随机数；如果是 'y'，则根据规则生成特定值
+        const v = c === 'x' ? r : (r & 0x3 | 0x8);
+        // 将结果转换为十六进制字符串
         return v.toString(16);
     });
 }
 
 module.exports = {
     randomId
-}
-
-
-
-
-
+};

src/utils/log-util.js

@@ -1,18 +1,22 @@
 /**
+ * 生成一个格式化字符串数组，用于 `console.log` 的多样式输出。
  *
+ * 该函数接受一个包含消息和样式的数组，生成一个格式化字符串，用于将消息和样式一一对应。
+ * 例如，输入 `["Hello", "color: red", "World", "color: blue"]`，输出 `"%c%s%c%s"`。
  *
- *
- * @param messageAndStyleArray
- * @return {string}
+ * @param {Array<string>} messageAndStyleArray - 包含消息和样式的数组。消息和样式交替出现，例如 `["消息1", "样式1", "消息2", "样式2"]`。
+ * @return {string} - 返回一个格式化字符串，例如 `"%c%s%c%s"`，用于 `console.log` 的多样式输出。
  */
 function genFormatArray(messageAndStyleArray) {
     const formatArray = [];
+    // 遍历数组，每两个元素（消息和样式）生成一个 "%c%s"
     for (let i = 0, end = messageAndStyleArray.length / 2; i < end; i++) {
         formatArray.push("%c%s");
     }
+    // 将数组拼接成一个字符串
     return formatArray.join("");
 }
 
 module.exports = {
     genFormatArray
-}
+};

src/utils/scope-util.js

@@ -1,15 +1,17 @@
 /**
+ * 获取 `unsafeWindow` 对象，用于在油猴脚本中访问或修改全局 `window` 对象。
  *
- * 在油猴脚本内部的沙箱机制，不让修改window上的变量，要修改的话需要通过 unsafeWindow，需要修改的地方全局调用此方法获取，这样后面方便知道都有哪些地方用到了unsafeWindow
+ * 油猴脚本默认运行在一个沙箱环境中，无法直接修改全局 `window` 对象。
+ * 通过 `unsafeWindow` 可以绕过沙箱机制，直接访问或修改全局 `window` 对象。
+ * 使用此方法封装 `unsafeWindow` 的调用，便于后续追踪哪些地方使用了 `unsafeWindow`。
  *
- * https://wiki.greasespot.net/UnsafeWindow
- *
- * @returns {*}
+ * @see https://wiki.greasespot.net/UnsafeWindow - 油猴脚本中 `unsafeWindow` 的官方文档。
+ * @returns {Window} - 返回全局的 `unsafeWindow` 对象。
  */
 function getUnsafeWindow() {
     return unsafeWindow;
 }
 
 module.exports = {
     getUnsafeWindow,
-}
+};

src/utils/string-util.js

@@ -1,8 +1,9 @@
 /**
+ * 将字符串重复指定次数并拼接成一个新字符串。
  *
- * @param s
- * @param times
- * @return {string}
+ * @param {string} s - 需要重复的字符串。
+ * @param {number} times - 重复的次数。
+ * @return {string} - 返回重复拼接后的字符串。
  */
 function repeat(s, times) {
     const msgs = [];
@@ -13,10 +14,11 @@ function repeat(s, times) {
 }
 
 /**
+ * 将字符串填充到指定长度。如果字符串长度不足，则在末尾填充空格。
  *
- * @param s
- * @param length
- * @return {*|string}
+ * @param {string} s - 需要填充的字符串。
+ * @param {number} length - 目标长度。
+ * @return {string} - 返回填充后的字符串。如果字符串长度已经大于或等于目标长度，则返回原字符串。
  */
 function fillToLength(s, length) {
     if (s.length >= length) {
@@ -29,4 +31,4 @@ function fillToLength(s, length) {
 module.exports = {
     repeat,
     fillToLength,
-}
+};

src/utils/url-util.js

@@ -1,56 +1,64 @@
 /**
+ * 获取 URL 的基础路径（包括协议、域名和路径部分，但不包括文件名）。
  *
- * @param urlString {String} "https://example.com/path/to/page.html"
- * @return
+ * @param {string} urlString - 完整的 URL 字符串，例如 "https://example.com/path/to/page.html"。
+ * @return {string} - 返回 URL 的基础路径，例如 "https://example.com/path/to/"。
  */
 function urlBasePath(urlString) {
     const url = new URL(urlString);
+    // 获取基础路径（包括协议、域名和路径部分，但不包括文件名）
     const basePath = `${url.origin}${url.pathname.substring(0, url.pathname.lastIndexOf("/") + 1)}`;
     // console.log(basePath); // 输出: https://example.com/path/to/
     return basePath;
 }
 
 /**
+ * 将 script 的 src 格式化为完整的 URL。
  *
- * 把script的src格式化，统一为url的形式
+ * 支持以下格式的 script src：
+ * 1. 完整的 URL（以 "http://" 或 "https://" 开头）。
+ * 2. CDN URL（以 "//" 开头）。
+ * 3. 相对路径（以 "./" 开头）。
+ * 4. 省略域名的路径（以 "/" 开头）。
+ * 5. 其他相对路径。
  *
- * @param scriptSrc {String}
- * @return
+ * @param {string} scriptSrc - script 的 src 属性值。
+ * @return {string} - 返回格式化后的完整 URL。
  */
 function formatScriptSrcToUrl(scriptSrc) {
 
-    // 强制requestUrl是一个字符串
-    // 比如可能会是一个TrustedScriptURL
+    // 强制将 scriptSrc 转换为字符串（例如，处理 TrustedScriptURL 类型）
     scriptSrc = scriptSrc + "";
 
-    // 正常格式直接返回
+    // 如果已经是完整的 URL，直接返回
     if (scriptSrc.startsWith("http://") || scriptSrc.startsWith("https://")) {
         return scriptSrc;
     }
 
-    // 兼容CDN URL
+    // 处理 CDN URL（以 "//" 开头）
     // 示例："//statics.moonshot.cn/kimi-chat/shared-K0TvIN461soURJCs7nh6uxcQiCM_.04bc3959.async.js"
     if (scriptSrc.startsWith("//")) {
         return "https:" + scriptSrc;
     }
 
-    // 相对路径： "./js/login/log-utils1.1.js"
+    // 处理相对路径（以 "./" 开头）
+    // 示例："./js/login/log-utils1.1.js"
     if (scriptSrc.startsWith("./")) {
         return urlBasePath(window.location.href) + scriptSrc.substring(2, scriptSrc.length);
     }
 
-    // 兼容省略域名的情况
-    // 数据样例："/logos/2024/moon/december-r4/december.js"
+    // 处理省略域名的路径（以 "/" 开头）
+    // 示例："/logos/2024/moon/december-r4/december.js"
     if (scriptSrc.startsWith("/")) {
         return window.location.origin + scriptSrc;
     }
 
-    // 相对路径
-    // "static/js/chunk-19a101ae.45e69b5c.js"
+    // 处理其他相对路径
+    // 示例："static/js/chunk-19a101ae.45e69b5c.js"
     return window.location.origin + "/" + scriptSrc;
 }
 
 module.exports = {
     urlBasePath,
     formatScriptSrcToUrl,
-}
+};