Item 68: Use TSDoc for API Comments

要点

• Use JSDoc-/TSDoc-formatted comments to document exported functions, classes, and types. This helps editors surface information for your users when it's most relevant.
• Use @param, @returns, and Markdown for formatting.
• Avoid including type information in documentation (see pass:[Item 31]).
• Mark deprecated APIs with @deprecated.
• 使用 JSDoc/TSDoc 格式的注释来记录导出的函数、类和类型。这有助于编辑器在最相关时为用户提供信息。
• 使用 @param、@returns 和 Markdown 来进行格式化。
• 避免在文档中包含类型信息（参见第 31 项）。
• 使用 @deprecated 标记已废弃的 API。

正文

// Generate a greeting. Result is formatted for display.
function greet(name: string, title: string) {
  return `Hello ${title} ${name}`
}

💻 playground

---

/** Generate a greeting. Result is formatted for display. */
function greetJSDoc(name: string, title: string) {
  return `Hello ${title} ${name}`
}

💻 playground

---

/**
 * Generate a greeting.
 * @param name Name of the person to greet
 * @param title The person's title
 * @returns A greeting formatted for human consumption.
 */
function greetFullTSDoc(name: string, title: string) {
  return `Hello ${title} ${name}`
}

💻 playground

---

/** A measurement performed at a time and place. */
interface Measurement {
  /** Where was the measurement made? */
  position: Vector3D
  /** When was the measurement made? In seconds since epoch. */
  time: number
  /** Observed momentum */
  momentum: Vector3D
}

💻 playground