How to document your JavaScript package

如何为你的 JavaScript 包编写文档

这篇博客文章介绍了如何为开源包编写明确且易于理解的文档，并确保用户可以在他们的工作流程中访问这些文档。

为何选择 JSDoc？

• JSDoc 是一种将你的代码注释变成多种格式（如 HTML、markdown、JSON 等）文档的工具。
• 它有助于在 IDE 或文本编辑器中提供有用的信息。

基础介绍

• JSDoc 注释以 /** 开始，在 / 结束。
• 需要提供函数或方法的简洁描述。

提供良好的类型信息

• 类型信息有助于编辑器中实现参数和返回值的自动补全。

使用标签

• @param、@returns 和 @typeParam 等标签可以提供有关函数或类的更多信息。

增加示例

• 使用 @example 标签将示例添加到 JSDoc 注释中，有助于用户快速理解如何使用你的库。

文档应记录什么？

• 记录包导出的每个符号，包括函数、类、接口和类型别名。
• 对类和接口的每个方法或属性进行文档化。

使用 markdown

• Markdown 可以让你在 JSDoc 中组织更可读、更引人入胜的文档，并可以使用链接。