Repository navigation
[docs]: Trim godoc to caller-visible contract - #211
Merged
Merged
Conversation
Vaughan-Temporal
approved these changes
Oct 7, 2026
Many doc comments had grown into multi-paragraph essays covering design rationale, history, and why alternatives were rejected. That context is useful once, during review, but every later reader of the godoc has to scroll past it to find the part that matters to them. This cuts identifier doc comments down to what the thing is plus the constraints a caller can observe: errors and status codes, nil handling, ordering, lifecycle and close obligations, concurrency safety, and operator or security warnings. Rationale that explains a non-obvious guard in unexported code is kept in condensed form so the guard does not look removable. Package docs and the examples are left alone, since they are where an overview or a walkthrough belongs. While here, the codecserver docs still described per-upstream proxies, which no longer exist; they now refer to each upstream's forwarder. Only comments change.
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! 🚀 New features to boost your workflow:
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Many doc comments had grown into multi-paragraph essays covering design rationale, history, and why alternatives were rejected. That context is useful once, during review, but every later reader of the godoc has to scroll past it to find the part that matters to them.
This cuts identifier doc comments down to what the thing is plus the constraints a caller can observe: errors and status codes, nil handling, ordering, lifecycle and close obligations, concurrency safety, and operator or security warnings. Rationale that explains a non-obvious guard in unexported code is kept in condensed form so the guard does not look removable. Package docs and the examples are left alone, since they are where an overview or a walkthrough belongs.
While here, the codecserver docs still described per-upstream proxies, which no longer exist; they now refer to each upstream's forwarder.
Only comments change.