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

x/tools/internal/telemetry: poor package comment #36238

Open
robpike opened this issue Dec 21, 2019 · 4 comments
Open

x/tools/internal/telemetry: poor package comment #36238

robpike opened this issue Dec 21, 2019 · 4 comments

Comments

@robpike
Copy link
Contributor

@robpike robpike commented Dec 21, 2019

I know it's an internal package, but the package doc for internal/telemetry is poorly conceived:

Package telemetry provides an opinionated set of packages that cover the
main concepts of telemetry in an implementation agnostic way. As a library
author you should look at...

It doesn't say what the package does. It claims that the package is "opinionated' (a passive-agressive way to say, we don't care what you think about the design) but gives no hint at what that opinion leads to. Avoid editorializing, just say what the package does. And it wouldn't hurt to say what "telemetry" is and what it's measuring, and for whom.

@dmitshur dmitshur changed the title tools/internal/telemetry: poor package comment x/tools/internal/telemetry: poor package comment Dec 23, 2019
@gopherbot gopherbot added this to the Unreleased milestone Dec 23, 2019
@gopherbot gopherbot added the Tools label Dec 23, 2019
@dmitshur

This comment has been minimized.

Copy link
Member

@dmitshur dmitshur commented Dec 23, 2019

Thanks for making this improvement suggestion.

For reference, before the telemetry packages were moved out of internal/lsp in CL 190403, the package comment was:

// Package telemetry provides the hooks and adapters to allow use of telemetry
// throughout gopls.
package telemetry

I suspect it's challenging to describe what package telemetry does because "telemetry" is a very broad term covering a large problem space. Perhaps it can be said that the package provides common base types that are used by other golang.org/x/tools/internal/telemetry/... packages.

/cc @ianthehat

@robpike

This comment has been minimized.

Copy link
Contributor Author

@robpike robpike commented Dec 23, 2019

The original comment was more helpful. I'm curious why it was changed.

@goku321

This comment has been minimized.

Copy link

@goku321 goku321 commented Dec 30, 2019

Can I help in fixing this?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
5 participants
You can’t perform that action at this time.