如何用JSDoc注释生成API文档但不写入.d.ts声明文件？

1. 用@ignore标签快速实现 #

TypeScript在生成.d.ts文件时，会自动忽略带有@ignore标签的函数，但绝大多数API文档生成工具（比如JSDoc、Typedoc）默认不会过滤这类函数，刚好满足「仅文档保留，声明文件排除」的需求。

示例代码：

/**
 * 这是一个仅用于API文档展示的工具函数
 * @ignore
 */
function tempHelper() {
  // 函数逻辑
}

注意：如果用Typedoc生成文档，别开启--excludePrivate这类会过滤@ignore内容的配置，不然文档里也看不到这个函数。

2. 用@internal配合tsconfig配置 #

如果需要更严谨的区分，可以用@internal标签，结合TypeScript的配置来实现：

• 给目标函数添加@internal标签：

/**
 * 仅在API文档中展示的内部辅助函数
 * @internal
 */
function internalUtility() {
  // 函数逻辑
}

• 在tsconfig.json里开启stripInternal选项，这样TypeScript生成声明文件时会自动排除带@internal的函数：

{
  "compilerOptions": {
    "declaration": true,
    "stripInternal": true,
    // 其他编译配置...
  }
}

• 配置API文档工具（比如Typedoc）时，设置includeInternal: true，确保这些函数能出现在文档里。

3. 自定义文档标签+手动排除 #

如果上面两种标签不符合你的工具链，可以给函数加自定义标签（比如@docOnly），然后在API文档工具的配置里指定包含这类标签的函数，同时在TypeScript的声明生成时手动排除这些函数——比如把它们单独放在一个文件里，在tsconfig.json的exclude里配置跳过该文件。

内容的提问来源于stack exchange，提问作者alec