如何为jQuery插件写文档

为 jQuery 插件写文档，核心是让用户看得懂、用得上、少踩坑。下面从「内容结构、写作方式、工具选择、示例模板」几个方面讲。

一、jQuery 插件文档应包含的内容

一个合格的 jQuery 插件文档通常包括：

1. 插件简介

• 插件名称
• 功能说明（解决什么问题）
• 适用场景
• 浏览器兼容性

2. 安装方式

• CDN 引入
• npm 安装
• 本地引入

<script src="jquery.min.js"></script>
<script src="jquery.myPlugin.js"></script>

3. 基本用法

• 最简示例
• DOM 结构要求（如果有）

$('#demo').myPlugin();

4. 参数说明（Options）

用表格清晰列出：

$('#demo').myPlugin({
  speed: 500,
  color: '#f00'
});

5. 方法（Methods）

说明如何调用插件方法：

$('#demo').myPlugin('destroy');

6. 事件（Events）

$('#demo').on('myPlugin:done', function () {
  console.log('完成');
});

7. 回调（Callbacks）

$('#demo').myPlugin({
  onComplete: function () {
    alert('完成');
  }
});

8. 示例 / Demo

• 在线 Demo 链接
• 完整 HTML 示例

9. 常见问题（FAQ）

• 不生效怎么办？
• 是否支持链式调用？
• 能否多次初始化？

二、写作原则

✅ 先讲“怎么用”，再讲“怎么配”
✅ 用真实示例，不要只写 API
✅ 避免过多实现细节
✅ 统一命名风格（camelCase / kebab-case）

三、推荐文档形式

1. README.md（最常用）

适合 GitHub 项目

2. JSDoc 注释 + 自动文档

/**
 * @param {Object} options
 * @param {Number} options.speed
 */

工具：

• JSDoc
• Docdash

3. 官方网站 / Wiki

适合成熟插件

四、jQuery 插件文档示例模板

# jQuery MyPlugin

## 简介
一个轻量级的提示插件。

## 安装
```html
<script src="jquery.min.js"></script>
<script src="jquery.myPlugin.js"></script>

使用

$('#btn').myPlugin();

参数

方法

• destroy()

事件

• myPlugin:show

---

如果你愿意，我可以：
- 帮你写**某个具体 jQuery 插件的文档**
- 给你一个**完整插件 + 文档示例**
- 按 **GitHub / npm 风格**整理文档

只要告诉我插件功能即可。