uptrace/bun

Request: Add GoDoc comments to exported API types/functions

Open

#1,283 创建于 2025年10月4日

在 GitHub 查看
 (1 评论) (0 反应) (0 负责人)Go (279 fork)user submission
documentationgood first issuehelp wanted

仓库指标

Star
 (4,826 star)
PR 合并指标
 (平均合并 76天 17小时) (30 天内合并 1 个 PR)

描述

Summary

  • Most exported types and functions currently ship without GoDoc; for example, bun.DB and bun.SelectQuery show empty documentation blocks on pkg.go.dev.
  • As a production user, this makes it harder to understand intended semantics without diving into implementation or external docs.

Why

  • IDEs and pkg.go.dev rely on GoDoc to surface quick info. Without it, new team members end up spelunking through the source or switching back and forth with https://bun.uptrace.dev/.
  • External docs help with guides, but inline API docs would clarify parameters, return values, and gotchas at the call site.

Proposal

  1. Confirm there is no policy against GoDoc in this repo. (I did not find an issue explaining one; closest is the documentation request in #1145 which was closed as stale.)
  2. If maintainers agree, I can start opening PRs that add succinct GoDoc comments to exported symbols, beginning with core files like db.go, query_select.go, and query_insert.go.
  3. Keep comments focused on API intent, optionally linking to the official docs for deeper dives to avoid duplication.

Happy to adjust scope or process (e.g., batch vs. incremental PRs) depending on maintainer preference.

贡献者指南