TypeStrong/typedoc中NoInfer类型参数的文档生成问题分析

问题背景

在TypeScript 5.4中引入的NoInfer工具类型是一个非常有用的特性，它允许开发者阻止TypeScript从特定位置推断泛型类型参数。然而，当这个特性与TypeStrong/typedoc结合使用时，发现了一个文档生成方面的问题。

问题现象

当函数参数类型被包装在NoInfer中时，例如NoInfer<C>，TypeDoc在生成的文档中会完全移除这个类型参数C的显示。这导致文档使用者无法看到参数原本的类型信息，尽管NoInfer只是影响了类型推断行为，并不改变参数的实际类型。

技术细节

NoInfer的实现原理是通过一个特殊的类型标记来阻止TypeScript的推断机制。它本质上是一个类型级别的"提示"，告诉编译器不要从这个位置推断泛型参数。但是，从文档的角度来看，这个类型信息仍然是有价值的：

1. 参数的实际类型仍然是C
2. 开发者需要知道这个参数接受什么类型的值
3. 文档应该反映API的实际契约，而不仅仅是类型推断细节

影响范围

这个问题会影响所有使用NoInfer包装类型参数的API文档生成。特别是那些设计良好的泛型API，其中某些参数故意使用NoInfer来引导开发者正确使用类型参数。

解决方案

TypeDoc应该修改其类型处理逻辑，在遇到NoInfer包装的类型时：

1. 保留内部类型的信息显示
2. 可以考虑添加注释说明这个类型不会被用于推断
3. 保持类型层次结构的完整性

最佳实践建议

对于库作者来说，在使用NoInfer时可以考虑：

1. 添加额外的JSDoc注释说明参数类型
2. 在文档中明确说明NoInfer的使用意图
3. 考虑是否真的需要阻止类型推断，或者可以通过其他设计达到目的

总结

TypeScript的类型系统特性与文档生成工具的交互是一个需要持续关注的领域。NoInfer带来的文档生成问题提醒我们，类型系统的高级特性需要考虑其在文档层面的表现。良好的文档应该准确反映API的设计意图，包括类型推断行为的特殊处理。