编写文档 - 文档

编写文档对于包的成功至关重要。JSR 使包作者能够轻松拥有出色的文档，因为它会根据包源代码中的 JSDoc 注释生成文档。

此生成的文档显示在包页面上。此文档还将以完成和悬停描述的形式显示在用户的编辑器中。

文档有两个重要部分

**符号文档**: 这是对包导出的每个单独函数、接口、常量或类的文档
模块文档: 这是对包中每个导出模块的文档 - 它充当模块中所有符号的概述或摘要

符号文档

要添加符号的文档，请在符号上方添加 JSDoc 注释

+ /** This function adds the two passed numbers together. */
  export function add(a: number, b: number): number {
    return a + b;
  }

注释也可以是多行注释

+ /**
+  * This function takes two numbers as input, and then adds these numbers using
+  * floating point math.
+  */
  export function add(a: number, b: number): number {
    return a + b;
  }

对于函数，可以为特定参数或返回类型添加文档

  /**
   * Search the database with the given query.
   *
+  * @param query This is the query to search with. It should be less than 50 chars to ensure good performance.
+  * @param limit The number of items to return. If unspecified, defaults to 20.
+  * @returns The array of matched items.
   */
  export function search(query: string, limit: number = 20): string[];

对于更复杂的符号，通常最好包含一个演示如何使用该函数的示例

  /**
   * Search the database with the given query.
   *
+  * ```ts
+  * search("Alan") // ["Alan Turing", "Alan Kay", ...]
+  * ```
   */
  export function search(query: string, limit: number = 20): string[];

接口也可以用 JSDoc 进行注释。它们的属性和方法也可以进行注释

/** The options bag to pass to the {@link search} method. */
export interface SearchOptions {
  /** The maximum number of items to return from the search. Defaults to 50 if
   * unspecified. */
  limit?: number;
  /** Skip the given number of items. This is helpful to implement pagination.
   * Defaults to 0 (do not skip) if not specified. */
  skip?: number;

  /** The function to call if the {@link search} function needs to show warnings
   * to the user. If not specified, warnings will be silently swallowed. */
  reportWarning?(message: string): void;
}

如上所示，{@link <ident>} 可用于在 JSDoc 中的符号之间建立链接。这些将在生成的文档中变为可点击的链接。

类可以类似于接口和函数进行注释

/**
 * A class to represent a person.
 */
export class Person {
  /** The name of the person. */
  name: string;
  /** The age of the person. */
  age: number;

  /**
   * Create a new person with the given name and age.
   * @param name The name of the person.
   * @param age The age of the person. Must be non-negative.
   */
  constructor(name: string, age: number) {
    if (age < 0) {
      throw new Error("Age cannot be negative");
    }
    this.name = name;
    this.age = age;
  }

  /** Print a greeting to the console. */
  greet() {
    console.log(
      `Hello, my name is ${this.name} and I am ${this.age} years old.`,
    );
  }
}

模块文档

不仅可以对符号进行文档化。模块也可以进行文档化。这对于概述模块及其导出符号很有用。

要对模块进行文档化，请在模块文件顶部添加 JSDoc 注释，并在注释中的任何位置包含 @module 标签

+ /**
+  * This module contains functions to search the database.
+  * @module
+  */
  
  /** The options bag to pass to the {@link search} method. */
  export interface SearchOptions {}
  
  /** Search the database with the given query. */
  export function search(query: string, options?: SearchOptions): string[];

您也可以在模块文档中包含示例

  /**
   * @module
   *
   * This module contains functions to search the database.
   *
+  * ```ts
+  * import { search } from "@luca/search";
+  *
+  * search("Alan") // ["Alan Turing", "Alan Kay", ...]
+  * ```
   */