Skip to content

Request: Add GoDoc comments to exported API types/functions #1283

@kotahorii

Description

@kotahorii

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 No documentation or information at all about AppendQuery #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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationgood first issueGood for newcomershelp wantedExtra attention is needed

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions