撰寫文件 - 文件 - JSR 繁體中文

撰寫文件對套件的成功至關重要。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", ...]
+  * ```
   */