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

log/slog: Package doc mistakes / inconsistencies #62286

Closed
icza opened this issue Aug 25, 2023 · 3 comments
Closed

log/slog: Package doc mistakes / inconsistencies #62286

icza opened this issue Aug 25, 2023 · 3 comments
Labels
Documentation help wanted NeedsFix The path to resolution is known, but the work has not been done.
Milestone

Comments

@icza
Copy link

icza commented Aug 25, 2023

What version of Go are you using (go version)?

$ go version
go version go1.21.0 linux/amd64

Does this issue reproduce with the latest release?

Yes

What did you do?

Visited the package doc of log/slog package: https://pkg.go.dev/log/slog

What did you expect to see?

I found 3 possible mistakes in the package doc:

  1. In Attrs and Values section:

The call

logger.LogAttrs(ctx, slog.LevelInfo, "hello", slog.Int("count", 3))

is the most efficient way to achieve the same output as

slog.Info("hello", "count", 3)

The last line should be:

logger.InfoContext(ctx, "hello", "count", 3)
  1. In the Wrapping output methods section:

For instance, if you define this function in file mylog.go:

func Infof(format string, args ...any) {
    slog.Default().Info(fmt.Sprintf(format, args...))
}

and you call it like this in main.go:

Infof(slog.Default(), "hello, %s", "world")

If the call to Infof() passes a logger, the signature should contain it and the body should use it, e.g.:

 func Infof(logger *slog.Logger, format string, args ...any) {
     logger.Info(fmt.Sprintf(format, args...))
 }
  1. I would also like to note that the rendered package doc contains the text [HandlerOptions.Level] at multiple places, without being rendered as link. There are other examples too, e.g. [HandlerOptions.ReplaceAttr].
@bcmills bcmills added Documentation help wanted NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. labels Aug 25, 2023
@bcmills bcmills added this to the Backlog milestone Aug 25, 2023
@bcmills
Copy link
Contributor

bcmills commented Aug 25, 2023

(attn @jba)

@seankhliao
Copy link
Member

3 would be this issue: #61394

@seankhliao seankhliao added NeedsFix The path to resolution is known, but the work has not been done. and removed NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. labels Aug 26, 2023
@gopherbot
Copy link

Change https://go.dev/cl/523196 mentions this issue: log/slog: package doc fixes

@dmitshur dmitshur modified the milestones: Backlog, Go1.22 Aug 30, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Documentation help wanted NeedsFix The path to resolution is known, but the work has not been done.
Projects
None yet
Development

No branches or pull requests

5 participants