编辑“︁JavaScript文档编写”︁

= JavaScript文档编写 =

'''JavaScript文档编写'''是指为JavaScript代码编写清晰、结构化的说明文档，通常使用标准化格式（如JSDoc）来描述函数、类、模块和变量的用途、参数、返回值及示例。良好的文档能提升代码可维护性，帮助团队成员理解代码逻辑，并支持自动化工具生成API参考。

== 为什么需要文档编写 ==
* '''代码可读性'''：文档帮助开发者快速理解代码功能，减少学习成本。
* '''团队协作'''：统一格式的文档便于多人协作开发。
* '''工具支持'''：JSDoc等工具可通过文档生成HTML参考页面或集成到IDE中提供智能提示。
* '''类型检查'''：通过类型注解（如<code>@type</code>）可辅助TypeScript或Flow进行静态分析。

== JSDoc基础语法 ==
JSDoc以<code>/** ... */</code>注释块形式出现，常用标签如下：

{| class="wikitable"
|+ 常用JSDoc标签
! 标签 !! 用途 !! 示例
|-
| <code>@param</code> || 描述函数参数 || <code>@param {string} name - 用户名</code>
|-
| <code>@returns</code> || 描述返回值 || <code>@returns {number} 计算结果</code>
|-
| <code>@throws</code> || 描述可能抛出的错误 || <code>@throws {Error} 参数无效时抛出</code>
|-
| <code>@example</code> || 提供用法示例 || <code>@example add(1, 2) // => 3</code>
|}

=== 基础示例 ===
<syntaxhighlight lang="javascript">
/**
 * 计算两数之和
 * @param {number} a - 第一个加数
 * @param {number} b - 第二个加数
 * @returns {number} 两数之和
 * @example
 * add(2, 3); // => 5
 */
function add(a, b) {
  return a + b;
}
</syntaxhighlight>

== 高级文档技巧 ==
=== 类型定义 ===
使用<code>@typedef</code>定义复杂类型：
<syntaxhighlight lang="javascript">
/**
 * @typedef {Object} User
 * @property {string} name - 用户姓名
 * @property {number} age - 用户年龄
 */

/**
 * @param {User} user - 用户对象
 */
function greet(user) {
  console.log(`Hello, ${user.name}!`);
}
</syntaxhighlight>

=== 泛型支持 ===
通过<code>@template</code>标注泛型：
<syntaxhighlight lang="javascript">
/**
 * @template T
 * @param {T[]} items - 泛型数组
 * @returns {T} 最后一个元素
 */
function last(items) {
  return items[items.length - 1];
}
</syntaxhighlight>

== 实际案例 ==
=== 类文档示例 ===
<syntaxhighlight lang="javascript">
/**
 * 表示一个二维坐标点
 * @class
 */
class Point {
  /**
   * @param {number} x - X坐标
   * @param {number} y - Y坐标
   */
  constructor(x, y) {
    this.x = x;
    this.y = y;
  }

  /**
   * 计算到另一点的距离
   * @param {Point} other - 另一个点
   * @returns {number} 两点距离
   * @throws {Error} 参数不是Point实例时抛出
   */
  distanceTo(other) {
    if (!(other instanceof Point)) {
      throw new Error('参数必须是Point实例');
    }
    return Math.sqrt((this.x - other.x) ** 2 + (this.y - other.y) ** 2);
  }
}
</syntaxhighlight>

=== 模块文档示例 ===
<syntaxhighlight lang="javascript">
/**
 * 数学工具模块
 * @module mathUtils
 */

/**
 * 计算阶乘
 * @param {number} n - 输入数字
 * @returns {number} n的阶乘
 * @see {@link https://en.wikipedia.org/wiki/Factorial|维基百科}
 */
export function factorial(n) {
  return n <= 1 ? 1 : n * factorial(n - 1);
}
</syntaxhighlight>

== 文档生成工具 ==
常用工具链配置：
<mermaid>
graph LR
  A[JavaScript代码] --> B[JSDoc注释]
  B --> C[文档生成工具]
  C --> D[HTML文档]
  C --> E[Markdown文档]
</mermaid>

安装JSDoc工具：
<syntaxhighlight lang="bash">
npm install -g jsdoc
</syntaxhighlight>

生成HTML文档：
<syntaxhighlight lang="bash">
jsdoc yourFile.js -d ./docs
</syntaxhighlight>

== 最佳实践 ==
1. '''及时更新'''：代码修改时同步更新文档
2. '''避免冗余'''：不重复代码中明显的信息
3. '''使用Markdown'''：在描述中支持**加粗**、`代码`等格式
4. '''版本标注'''：通过<code>@since</code>标记功能引入版本
5. '''交叉引用'''：使用<code>@see</code>链接到相关函数

=== 数学公式示例 ===
对于涉及算法的函数，可使用LaTeX描述公式：
<math>
\sum_{i=1}^{n} i^2 = \frac{n(n+1)(2n+1)}{6}
</math>

对应文档：
<syntaxhighlight lang="javascript">
/**
 * 计算平方和公式
 * @param {number} n - 上限值
 * @returns {number} 结果值
 * @example
 * sumOfSquares(3); // => 14 (1² + 2² + 3²)
 */
function sumOfSquares(n) {
  return n * (n + 1) * (2 * n + 1) / 6;
}
</syntaxhighlight>

== 总结 ==
JavaScript文档编写是专业开发的重要环节，通过标准化注释：
* 提升代码可维护性
* 支持自动化工具链
* 促进团队知识共享

初学者应从简单的<code>@param</code>和<code>@returns</code>开始，逐步掌握类型定义和模块化文档技巧。

[[Category:编程语言]]
[[Category:JavaScript]]
[[Category:Javascript最佳实践]]