JS 文档字符串示例

在编写 JavaScript 代码时，编写文档字符串非常重要。文档字符串包含函数或方法的说明，参数列表和返回值类型等信息，让其他开发人员更容易理解代码和使用它。

文档字符串基础

文档字符串是放置在函数或方法定义之前的注释。例如：

/**
 * 这是一个加法函数
 * 
 * @param {number} num1 - 第一个数字
 * @param {number} num2 - 第二个数字
 * @returns {number} 两个数字之和
 */
function add(num1, num2) {
  return num1 + num2;
}

在此示例中，文档字符串包含描述函数的注释和几个标记。

• @param 标记用于描述函数的参数，并指定每个参数的类型。
• @returns 标记用于描述函数的返回类型。

这些标记可以帮助其他开发人员更轻松地理解函数的行为。

文档字符串格式

文档字符串通常符合以下格式：

/**
 * 描述函数的作用和行为
 * 
 * @param {type} parameterName - 描述参数
 * @returns {returnType} 描述返回值
 */

以下是文档字符串中支持的标记和用途：

• @param：描述函数参数。格式为 {type} parameterName - parameterDescription。其中，{type} 表示参数的类型，parameterName 是参数名称，parameterDescription 是对参数的描述。如果参数有多个，可以列出多行 @param。
• @returns：描述函数返回值类型和描述。格式为 {returnType} returnDescription。其中，{returnType} 指定返回值类型，returnDescription 描述返回值的行为。只能有一个 @returns 声明。
• @throws：描述函数可能抛出的异常。格式为 {exception} description。{exception} 表示异常类型，description 描述异常的情况。可以有多个 @throws。
• @deprecated：标注函数不再推荐使用。可以包含替代函数的信息。
• @example：提供使用示例的代码片段。
• @see：与该函数相关的其他文档字符串或源代码元素的链接。
• @private：指示该函数是私有的，不应被其他模块使用。
• @public：指示该函数是公共的。

以下是一个例子：

/**
 * 取单个字符的代码点
 * 
 * @param {string} str - 需要被取码点的字符串
 * @param {number} index - 要取码点的字符所在字符串的下标
 * @returns {number} 码点 (Unicode code point) 的值
 * @throws {RangeError} 如果 `index` 超出了字符串的长度，就会抛出错误。
 * @deprecated 该函数已不再推荐使用。使用 `codePointAt()` 替代该函数。
 * @example
 * 
 * codePointAt('abc', 1);
 * // expected output: 98
 * 
 * codePointAt('❤️', 0);
 * // expected output: 10084
 * 
 * @see {@link https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Reference/Global_Objects/String/codePointAt MDN docs for String.prototype.codePointAt()}
 * @public
 */
function codePointAt(str, index) {
  const code = str.charCodeAt(index);

  if (Number.isNaN(code)) {
    throw new RangeError(`Invalid character index: ${index}`);
  }

  if (code < 0xd800 || code > 0xdfff) {
    return code;
  }

  const high = code & 0x3ff;
  const low = str.charCodeAt(index + 1) & 0x3ff;

  return ((high << 10) | low) + 0x10000;
}

总结

好的文档字符串能够极大地提高代码可读性和可维护性。在编写 JavaScript 代码时，要注意编写详细的文档字符串，并使用支持的标记以说明函数的参数和返回值，以便其他人能够更好地理解你的代码。