argon-theme/.kiro/specs/pjax-lazyload-fix/jsdoc-templates.md

# JSDoc 注释模板

本文档提供了 argontheme.js 中关键函数的 JSDoc 注释模板，可以直接复制使用。

## Cookie 操作

```javascript
/**
 * 设置 Cookie
 * @param {string} cname - Cookie 名称
 * @param {string} cvalue - Cookie 值
 * @param {number} exdays - 过期天数
 * @returns {void}
 * @example
 * setCookie('theme', 'dark', 365);
 */
function setCookie(cname, cvalue, exdays) { }

/**
 * 获取 Cookie
 * @param {string} cname - Cookie 名称
 * @returns {string} Cookie 值，不存在则返回空字符串
 * @example
 * const theme = getCookie('theme');
 */
function getCookie(cname) { }
```

## 多语言支持

```javascript
/**
 * 翻译文本
 * 根据当前语言设置返回对应的翻译文本
 * @param {string} text - 要翻译的文本（中文）
 * @returns {string} 翻译后的文本，如果没有翻译则返回原文
 * @example
 * const translated = __('发送成功');
 */
function __(text) { }
```

## 搜索功能

```javascript
/**
 * 搜索文章
 * 使用 PJAX 方式跳转到搜索结果页面
 * @param {string} word - 搜索关键词
 * @returns {void}
 * @example
 * searchPosts('JavaScript');
 */
function searchPosts(word) { }
```

## 瀑布流布局

```javascript
/**
 * 初始化瀑布流布局
 * 根据配置和屏幕宽度计算列数，动态调整文章卡片位置
 * 支持 1/2/3 列布局，响应式自适应
 * @returns {void}
 * @example
 * waterflowInit();
 * // 窗口大小改变时重新初始化
 * $(window).resize(waterflowInit);
 */
function waterflowInit() { }
```

## 图片懒加载

```javascript
/**
 * 初始化图片懒加载
 * 优先使用 IntersectionObserver API，不支持时降级到滚动监听
 * 清理旧的 Observer 实例，避免重复初始化
 * @returns {void}
 * @example
 * lazyloadInit();
 */
function lazyloadInit() { }

/**
 * 优化的图片加载函数
 * 使用 requestAnimationFrame 优化性能，避免布局抖动
 * 支持 fadeIn 和 slideDown 两种加载效果
 * @param {HTMLImageElement} img - 图片元素
 * @param {string} effect - 加载效果类型 ('fadeIn' 或 'slideDown')
 * @returns {void}
 * @example
 * loadImageOptimized(imgElement, 'fadeIn');
 */
function loadImageOptimized(img, effect) { }

/**
 * 应用加载效果
 * 为图片添加淡入或滑入动画效果
 * @param {HTMLImageElement} img - 图片元素
 * @param {string} effect - 加载效果类型 ('fadeIn' 或 'slideDown')
 * @returns {void}
 * @example
 * applyLoadEffectOptimized(imgElement, 'fadeIn');
 */
function applyLoadEffectOptimized(img, effect) { }

/**
 * 懒加载降级方案（滚动监听）
 * 当浏览器不支持 IntersectionObserver 时使用
 * 使用节流函数优化滚动事件性能
 * @param {NodeList} images - 图片元素列表
 * @param {string} effect - 加载效果类型
 * @param {number} threshold - 提前加载的阈值（像素）
 * @returns {void}
 * @example
 * lazyloadFallback(images, 'fadeIn', 800);
 */
function lazyloadFallback(images, effect, threshold) { }

/**
 * 立即加载所有图片
 * 当懒加载被禁用时调用，不应用任何加载效果
 * @returns {void}
 * @example
 * loadAllImagesImmediately();
 */
function loadAllImagesImmediately() { }
```

## PJAX 资源清理

```javascript
/**
 * 清理 Lazyload Observer
 * 断开 IntersectionObserver 连接并置空引用，防止内存泄漏
 * @returns {void}
 * @example
 * cleanupLazyloadObserver();
 */
function cleanupLazyloadObserver() { }

/**
 * 清理 Zoomify 实例
 * 销毁所有图片放大实例，移除相关 CSS 类
 * @returns {void}
 * @example
 * cleanupZoomifyInstances();
 */
function cleanupZoomifyInstances() { }

/**
 * 清理 Tippy 实例
 * 销毁所有 Tooltip 实例，释放相关资源
 * @returns {void}
 * @example
 * cleanupTippyInstances();
 */
function cleanupTippyInstances() { }

/**
 * 清理 Mermaid 实例
 * 清理已渲染的图表记录和相关资源
 * 移除图表容器的事件监听器
 * @returns {void}
 * @example
 * cleanupMermaidInstances();
 */
function cleanupMermaidInstances() { }

/**
 * 清理动态样式
 * 只清理标记为 data-dynamic="true" 的 style 标签
 * 保留主题核心样式
 * @returns {void}
 * @example
 * cleanupDynamicStyles();
 */
function cleanupDynamicStyles() { }

/**
 * 清理动态脚本
 * 只清理标记为 data-dynamic="true" 的 script 标签
 * @returns {void}
 * @example
 * cleanupDynamicScripts();
 */
function cleanupDynamicScripts() { }

/**
 * 清理事件监听器
 * 清理 Mermaid 相关的事件监听器
 * 防止事件监听器累积导致的内存泄漏
 * @returns {void}
 * @example
 * cleanupEventListeners();
 */
function cleanupEventListeners() { }

/**
 * 清理所有 PJAX 资源
 * 在 pjax:beforeReplace 事件中调用
 * 统一清理 Observer、第三方库实例、动态标签等
 * 确保页面切换时不会出现资源泄漏
 * @returns {void}
 * @example
 * $(document).on('pjax:beforeReplace', function() {
 *     cleanupPjaxResources();
 * });
 */
function cleanupPjaxResources() { }

/**
 * 重置 GT4 验证码
 * 在 pjax:end 事件中调用
 * 重置 Geetest 验证码实例，清空验证状态
 * @returns {void}
 * @example
 * $(document).on('pjax:end', function() {
 *     resetGT4Captcha();
 * });
 */
function resetGT4Captcha() { }
```

## 脚本执行

```javascript
/**
 * 执行单个脚本
 * 创建新的 script 元素并执行，复制所有属性
 * 提供错误隔离，单个脚本失败不影响其他脚本
 * @param {HTMLScriptElement} oldScript - 原始脚本元素
 * @returns {boolean} 是否执行成功
 * @example
 * const success = executeScript(scriptElement);
 */
function executeScript(oldScript) { }

/**
 * 执行容器内的所有内联脚本
 * 按 DOM 顺序依次执行，提供错误隔离
 * 只执行内联脚本，不执行外部脚本
 * @param {HTMLElement} container - 容器元素，默认为 document
 * @returns {Object} 执行结果统计 {total, success, failed}
 * @example
 * const result = executeInlineScripts(document.getElementById('content'));
 * console.log(`成功: ${result.success}, 失败: ${result.failed}`);
 */
function executeInlineScripts(container) { }
```

## 评论功能

```javascript
/**
 * 显示回复框
 * 滚动到评论框，显示回复信息，聚焦输入框
 * @param {number} commentID - 评论ID
 * @returns {void}
 * @example
 * reply(123);
 */
function reply(commentID) { }

/**
 * 取消回复
 * 隐藏回复信息，重置回复状态
 * @returns {void}
 * @example
 * cancelReply();
 */
function cancelReply() { }

/**
 * 编辑评论
 * 加载评论内容到输入框，切换到编辑模式
 * @param {number} commentID - 评论ID
 * @returns {void}
 * @example
 * edit(123);
 */
function edit(commentID) { }

/**
 * 取消编辑
 * 退出编辑模式，可选择是否清空输入框
 * @param {boolean} clear - 是否清空输入框
 * @returns {void}
 * @example
 * cancelEdit(true);
 */
function cancelEdit(clear) { }

/**
 * 发送评论
 * 验证表单，发送 AJAX 请求，处理响应
 * 支持回复评论、Markdown、私密评论等功能
 * @returns {void}
 * @example
 * postComment();
 */
function postComment() { }

/**
 * 编辑评论
 * 验证表单，发送 AJAX 请求，更新评论内容
 * @returns {void}
 * @example
 * editComment();
 */
function editComment() { }

/**
 * 切换评论置顶状态
 * 显示确认对话框，发送 AJAX 请求，更新 UI
 * @param {number} commentID - 评论ID
 * @param {boolean} pinned - 当前是否已置顶
 * @returns {void}
 * @example
 * toogleCommentPin(123, false);
 */
function toogleCommentPin(commentID, pinned) { }

/**
 * 删除评论
 * 显示确认对话框，发送 AJAX 请求，移除评论元素
 * @param {number} commentID - 评论ID
 * @returns {void}
 * @example
 * deleteComment(123);
 */
function deleteComment(commentID) { }
```

## 工具函数

```javascript
/**
 * 折叠过长评论
 * 检测评论高度，超过阈值则折叠
 * @returns {void}
 * @example
 * foldLongComments();
 */
function foldLongComments() { }

/**
 * 生成评论文字头像
 * 当 Gravatar 头像加载失败时，生成文字头像
 * @param {HTMLImageElement} img - 头像图片元素
 * @returns {void}
 * @example
 * generateCommentTextAvatar(imgElement);
 */
function generateCommentTextAvatar(img) { }

/**
 * 刷新评论文字头像
 * 遍历所有评论头像，为未加载的生成文字头像
 * @returns {void}
 * @example
 * refreshCommentTextAvatar();
 */
function refreshCommentTextAvatar() { }

/**
 * 根据 Hash 定位到页面元素
 * 平滑滚动到指定元素位置
 * @param {string} hash - Hash 值（如 #comment-123）
 * @param {number} durtion - 滚动动画时长（毫秒）
 * @param {string} easing - 缓动函数名称
 * @returns {void}
 * @example
 * gotoHash('#comment-123', 600, 'easeOutExpo');
 */
function gotoHash(hash, durtion, easing = 'easeOutExpo') { }

/**
 * 从 URL 中提取 Hash
 * @param {string} url - URL 字符串
 * @returns {string} Hash 值（包含 # 符号）
 * @example
 * const hash = getHash('https://example.com/post#comment-123');
 * // 返回: '#comment-123'
 */
function getHash(url) { }

/**
 * 显示文章过时信息 Toast
 * 检查文章发布时间，超过阈值则显示提示
 * @returns {void}
 * @example
 * showPostOutdateToast();
 */
function showPostOutdateToast() { }
```

## 第三方库初始化

```javascript
/**
 * 初始化 Zoomify（图片放大）
 * 清理旧实例，为图片添加放大功能
 * @returns {void}
 * @example
 * zoomifyInit();
 */
function zoomifyInit() { }

/**
 * 初始化 Pangu.js（中英文排版优化）
 * 为文章内容和评论添加空格
 * @returns {void}
 * @example
 * panguInit();
 */
function panguInit() { }

/**
 * 初始化 Clamp.js（文本截断）
 * 限制文本行数，添加省略号
 * @returns {void}
 * @example
 * clampInit();
 */
function clampInit() { }

/**
 * 初始化 Tippy.js（Tooltip）
 * 为引用、按钮等元素添加 Tooltip
 * @returns {void}
 * @example
 * tippyInit();
 */
function tippyInit() { }
```

## 颜色转换工具

```javascript
/**
 * RGB 转 HSL
 * @param {number} R - 红色值 (0-255)
 * @param {number} G - 绿色值 (0-255)
 * @param {number} B - 蓝色值 (0-255)
 * @returns {Object} {H: 色相(0-360), S: 饱和度(0-100), L: 亮度(0-100)}
 * @example
 * const hsl = rgb2hsl(255, 0, 0);
 * // 返回: {H: 0, S: 100, L: 50}
 */
function rgb2hsl(R, G, B) { }

/**
 * HSL 转 RGB
 * @param {number} h - 色相 (0-360)
 * @param {number} s - 饱和度 (0-100)
 * @param {number} l - 亮度 (0-100)
 * @returns {Object} {R: 红色(0-255), G: 绿色(0-255), B: 蓝色(0-255)}
 * @example
 * const rgb = hsl2rgb(0, 100, 50);
 * // 返回: {R: 255, G: 0, B: 0}
 */
function hsl2rgb(h, s, l) { }

/**
 * RGB 转 HEX
 * @param {number} r - 红色值 (0-255)
 * @param {number} g - 绿色值 (0-255)
 * @param {number} b - 蓝色值 (0-255)
 * @returns {string} HEX 颜色值（如 #FF0000）
 * @example
 * const hex = rgb2hex(255, 0, 0);
 * // 返回: '#FF0000'
 */
function rgb2hex(r, g, b) { }

/**
 * HEX 转 RGB
 * @param {string} hex - HEX 颜色值（如 #FF0000）
 * @returns {Object} {R: 红色(0-255), G: 绿色(0-255), B: 蓝色(0-255)}
 * @example
 * const rgb = hex2rgb('#FF0000');
 * // 返回: {R: 255, G: 0, B: 0}
 */
function hex2rgb(hex) { }

/**
 * RGB 转灰度值
 * 使用标准灰度转换公式: 0.299R + 0.587G + 0.114B
 * @param {number} R - 红色值 (0-255)
 * @param {number} G - 绿色值 (0-255)
 * @param {number} B - 蓝色值 (0-255)
 * @returns {number} 灰度值 (0-255)
 * @example
 * const gray = rgb2gray(255, 0, 0);
 * // 返回: 76
 */
function rgb2gray(R, G, B) { }

/**
 * HEX 转灰度值
 * @param {string} hex - HEX 颜色值（如 #FF0000）
 * @returns {number} 灰度值 (0-255)
 * @example
 * const gray = hex2gray('#FF0000');
 * // 返回: 76
 */
function hex2gray(hex) { }

/**
 * RGB 对象转字符串
 * @param {Object} rgb - RGB 对象 {R, G, B}
 * @returns {string} RGB 字符串（如 "255,0,0"）
 * @example
 * const str = rgb2str({R: 255, G: 0, B: 0});
 * // 返回: '255,0,0'
 */
function rgb2str(rgb) { }

/**
 * HEX 转 RGB 字符串
 * @param {string} hex - HEX 颜色值（如 #FF0000）
 * @returns {string} RGB 字符串（如 "255,0,0"）
 * @example
 * const str = hex2str('#FF0000');
 * // 返回: '255,0,0'
 */
function hex2str(hex) { }
```

## 主题颜色

```javascript
/**
 * Pickr 颜色对象转 HEX
 * @param {Object} color - Pickr 颜色对象
 * @returns {string} HEX 颜色值（如 #FF0000）
 * @example
 * const hex = pickrObjectToHEX(pickr.getColor());
 */
function pickrObjectToHEX(color) { }

/**
 * 更新主题颜色
 * 更新 CSS 变量，计算衍生颜色，可选保存到 Cookie
 * @param {string} color - HEX 颜色值
 * @param {boolean} setcookie - 是否保存到 Cookie
 * @returns {void}
 * @example
 * updateThemeColor('#FF0000', true);
 */
function updateThemeColor(color, setcookie) { }
```

## 打字效果

```javascript
/**
 * 打字效果（递归实现）
 * @param {jQuery} $element - jQuery 元素对象
 * @param {string} text - 要显示的文本
 * @param {number} now - 当前显示到第几个字符
 * @param {number} interval - 每个字符的间隔时间（毫秒）
 * @returns {void}
 * @example
 * typeEffect($('#banner-title'), 'Hello World', 0, 100);
 */
function typeEffect($element, text, now, interval) { }

/**
 * 开始打字效果
 * @param {jQuery} $element - jQuery 元素对象
 * @param {string} text - 要显示的文本
 * @param {number} interval - 每个字符的间隔时间（毫秒）
 * @returns {void}
 * @example
 * startTypeEffect($('#banner-title'), 'Hello World', 100);
 */
function startTypeEffect($element, text, interval) { }
```

## 其他工具

```javascript
/**
 * 生成随机字符串
 * @param {number} len - 字符串长度
 * @returns {string} 随机字符串
 * @example
 * const id = randomString(8);
 * // 返回: 'a3f9d2e1'
 */
function randomString(len) { }

/**
 * 获取 GitHub Repo 信息卡内容
 * 通过 GitHub API 获取仓库信息并显示
 * @returns {void}
 * @example
 * getGithubInfoCardContent();
 */
function getGithubInfoCardContent() { }

/**
 * 折叠长说说
 * 检测说说高度，超过阈值则折叠
 * @returns {void}
 * @example
 * foldLongShuoshuo();
 */
function foldLongShuoshuo() { }

/**
 * 懒加载表情包
 * 为表情包图片添加懒加载
 * @returns {void}
 * @example
 * lazyloadStickers();
 */
function lazyloadStickers() { }

/**
 * 在输入框中插入文本
 * 使用 execCommand 或降级方案插入文本
 * @param {string} text - 要插入的文本
 * @param {HTMLElement} input - 输入框元素
 * @returns {void}
 * @example
 * inputInsertText('[smile]', document.getElementById('comment_content'));
 */
function inputInsertText(text, input) { }

/**
 * 显示评论编辑记录
 * 通过 AJAX 获取评论编辑历史并显示
 * @param {number} id - 评论ID
 * @returns {void}
 * @example
 * showCommentEditHistory(123);
 */
function showCommentEditHistory(id) { }
```

## 使用说明

1. **复制对应的 JSDoc 注释**到函数定义前
2. **根据实际情况调整**参数说明和示例
3. **确保类型注解正确**（string, number, boolean, Object, Array 等）
4. **添加使用示例**帮助其他开发者理解函数用法

## 注意事项

- JSDoc 注释应该放在函数定义的正上方
- 参数说明要清晰明确，包含类型和用途
- 返回值说明要准确，void 表示无返回值
- 示例代码要简洁实用，展示典型用法
- 对于复杂函数，可以添加更详细的说明