Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

x/exp/event: poor package comment #47154

Closed
robpike opened this issue Jul 12, 2021 · 4 comments
Closed

x/exp/event: poor package comment #47154

robpike opened this issue Jul 12, 2021 · 4 comments
Labels
Documentation FrozenDueToAge NeedsFix The path to resolution is known, but the work has not been done.
Milestone
Unreleased

Comments

@robpike
Copy link
Contributor

robpike commented Jul 12, 2021

I ran go doc in x/exp/event to see what it does. This is what is reported for the package comment:

% go doc 
package event // import "golang.org/x/exp/event"

Package event provides the core functionality for observability that allows
libraries using it to interact well. It enforces the middle layer
interchange format, but allows both frontend wrappers and back end exporters
to customize the usage.
...
%

I learned nothing from this. Please provide a package comment that explains the purpose of the package.
@ianlancetaylor
Copy link
Contributor

CC @ianthehat

@seankhliao seankhliao added Documentation NeedsFix The path to resolution is known, but the work has not been done. labels Jul 13, 2021
@dmitshur dmitshur changed the title exp/event: poor package comment x/exp/event: poor package comment Jul 13, 2021
@gopherbot gopherbot added this to the Unreleased milestone Jul 13, 2021
@dmitshur
Copy link
Contributor

Possibly related issue #36238. Also CC @stamblerre.

@ianthehat
Copy link

The package and all things below it are very very experimental, not ready for anybody to actually use, and might still just be deleted (some of the sub packages definitely will be).
If it turns out to be a success, it will move out of experimental to somewhere real.
I do think it is reasonable to ask for a better package comment even in it's current state though, to at least make that much clear to anyone looking, I know that technically applies to all of x/exp but that package is even more experimental that most right now.
I will take this bug and close it when I do that.

@ianthehat ianthehat self-assigned this Jul 13, 2021
@gopherbot
Copy link

Change https://golang.org/cl/334489 mentions this issue: event: improve package documentation

@robpike robpike closed this as completed Nov 3, 2021
gopherbot pushed a commit to golang/exp that referenced this issue Nov 9, 2021
@ianthehat @ianlancetaylor
event: improve package documentation
9df80dc 
Fixes golang/go#47154

Change-Id: I178ae897af03a9bf284e3e8110d3b1440e5b978e
Reviewed-on: https://go-review.googlesource.com/c/exp/+/334489
Trust: Ian Cottrell <iancottrell@google.com>
Run-TryBot: Ian Cottrell <iancottrell@google.com>
TryBot-Result: Go Bot <gobot@golang.org>
Reviewed-by: Rob Pike <r@golang.org>
@golang golang locked and limited conversation to collaborators Jun 23, 2023
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Assignees
No one assigned
Labels
Documentation FrozenDueToAge NeedsFix The path to resolution is known, but the work has not been done.
Projects
None yet
Milestone
Unreleased
Development

No branches or pull requests
6 participants
@ianthehat @dmitshur @ianlancetaylor @robpike @gopherbot @seankhliao