请求: 为导出的 API 类型/函数添加 GoDoc 评论

摘要

• 目前大多数导出的类型和函数都没有 GoDoc;例如, bun.DB 和 bun.SelectQuery 在 pkg.go.dev 上显示了空的文档块。
• 作为生产级用户,这使得在没有深入了解实现或外部文档的情况下,更难理解预期的语义。
• 外部文档有助于指导使用,但内联 API 文档可以在调用点上解释参数、返回值和潜在的问题。

为什么

• IDE 和 pkg.go.dev 依赖 GoDoc 来提供快速信息。没有它,新的团队成员最终会深入研究源代码或来回切换到 https://bun.uptrace.dev/。
• 外部文档有助于指导使用,但内联 API 文档可以在调用点上解释参数、返回值和潜在的问题。

建议

1. 确认此仓库中没有禁止使用 GoDoc 的政策。(我没有找到解释此政策的问题;最近的一个是 #1145 中的文档请求,但已被关闭,因为已过时。)
2. 如果维护者同意,我可以开始提交 PR,为导出的符号添加简洁的 GoDoc 注释,首先从核心文件如 db.go,query_select.go 和 query_insert.go 开始。
3. 保持注释侧重于 API 意图,可选地链接到官方文档,以避免重复,从而进行更深入的研究。 根据维护者的偏好,我乐于调整范围或流程(例如批量 vs. 增量 PR)。