uptrace/bun

Request: Add GoDoc comments to exported API types/functions

Open

#1,283 opened on Oct 4, 2025

View on GitHub
 (1 comment) (0 reactions) (0 assignees)Go (4,826 stars) (279 forks)user submission
documentationgood first issuehelp wanted

Description

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.

Contributor guide

Tech stack
go
Domain
backenddocumentation
Issue type
documentation
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
2
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
half day
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
fresh
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
clear
Prerequisites
Basic Go knowledgeFamiliarity with GoDoc syntax
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
80
Research direction
This issue proposes adding GoDoc comments to exported types and functions in the uptrace/bun repository. The key files to target are db.go, query select.go, and query insert.go as mentioned in the issue body. First, confirm with maintainers that there is no policy against GoDoc (the issue requests this). Then, examine existing exported symbols in those files and add succinct GoDoc comments describing their purpose, parameters, and return values. Keep comments focused on API intent and optionally link to official documentation. The issue has a single comment from the author, and no other discussion or linked PRs, so it is available for contribution.