From ee349f9e2995499f66628dc573382939b6941b09 Mon Sep 17 00:00:00 2001 From: Abhinav Gupta Date: Tue, 2 Aug 2022 16:13:05 -0700 Subject: [PATCH] CI: Lint against 1.19 (#1141) We prefer to lint against the latest release. In Go 1.19, gofmt reformats godoc to match the [new format]. This change includes all the formatting changes that resulted from this. [new format]: https://go.dev/doc/comment --- .github/workflows/go.yml | 2 +- array_go118.go | 32 ++++++++--------- doc.go | 60 +++++++++++++++++--------------- http_handler.go | 20 +++++------ logger.go | 2 +- options.go | 2 +- sugar.go | 50 ++++++++++++++------------ zapcore/buffered_write_syncer.go | 30 ++++++++-------- zapcore/encoder.go | 9 +++-- zapcore/entry.go | 8 ++--- zapcore/error.go | 14 ++++---- zapcore/json_encoder.go | 4 ++- zapcore/sampler.go | 14 ++++---- zapio/writer.go | 16 ++++----- zaptest/logger.go | 6 ++-- 15 files changed, 141 insertions(+), 128 deletions(-) diff --git a/.github/workflows/go.yml b/.github/workflows/go.yml index f418b34d4..15b1cf1a0 100644 --- a/.github/workflows/go.yml +++ b/.github/workflows/go.yml @@ -15,7 +15,7 @@ jobs: matrix: go: ["1.17.x", "1.18.x", "1.19.x"] include: - - go: 1.18.x + - go: 1.19.x latest: true steps: diff --git a/array_go118.go b/array_go118.go index c80761d51..db36ec37f 100644 --- a/array_go118.go +++ b/array_go118.go @@ -36,27 +36,27 @@ import "go.uber.org/zap/zapcore" // Given an object that implements MarshalLogObject on the value receiver, you // can log a slice of those objects with Objects like so: // -// type Author struct{ ... } -// func (a Author) MarshalLogObject(enc zapcore.ObjectEncoder) error +// type Author struct{ ... } +// func (a Author) MarshalLogObject(enc zapcore.ObjectEncoder) error // -// var authors []Author = ... -// logger.Info("loading article", zap.Objects("authors", authors)) +// var authors []Author = ... +// logger.Info("loading article", zap.Objects("authors", authors)) // // Similarly, given a type that implements MarshalLogObject on its pointer // receiver, you can log a slice of pointers to that object with Objects like // so: // -// type Request struct{ ... } -// func (r *Request) MarshalLogObject(enc zapcore.ObjectEncoder) error +// type Request struct{ ... } +// func (r *Request) MarshalLogObject(enc zapcore.ObjectEncoder) error // -// var requests []*Request = ... -// logger.Info("sending requests", zap.Objects("requests", requests)) +// var requests []*Request = ... +// logger.Info("sending requests", zap.Objects("requests", requests)) // // If instead, you have a slice of values of such an object, use the // ObjectValues constructor. // -// var requests []Request = ... -// logger.Info("sending requests", zap.ObjectValues("requests", requests)) +// var requests []Request = ... +// logger.Info("sending requests", zap.ObjectValues("requests", requests)) func Objects[T zapcore.ObjectMarshaler](key string, values []T) Field { return Array(key, objects[T](values)) } @@ -90,17 +90,17 @@ type objectMarshalerPtr[T any] interface { // Given an object that implements MarshalLogObject on the pointer receiver, // you can log a slice of those objects with ObjectValues like so: // -// type Request struct{ ... } -// func (r *Request) MarshalLogObject(enc zapcore.ObjectEncoder) error +// type Request struct{ ... } +// func (r *Request) MarshalLogObject(enc zapcore.ObjectEncoder) error // -// var requests []Request = ... -// logger.Info("sending requests", zap.ObjectValues("requests", requests)) +// var requests []Request = ... +// logger.Info("sending requests", zap.ObjectValues("requests", requests)) // // If instead, you have a slice of pointers of such an object, use the Objects // field constructor. // -// var requests []*Request = ... -// logger.Info("sending requests", zap.Objects("requests", requests)) +// var requests []*Request = ... +// logger.Info("sending requests", zap.Objects("requests", requests)) func ObjectValues[T any, P objectMarshalerPtr[T]](key string, values []T) Field { return Array(key, objectValues[T, P](values)) } diff --git a/doc.go b/doc.go index 8638dd1b9..3c50d7b4d 100644 --- a/doc.go +++ b/doc.go @@ -32,7 +32,7 @@ // they need to count every allocation and when they'd prefer a more familiar, // loosely typed API. // -// Choosing a Logger +// # Choosing a Logger // // In contexts where performance is nice, but not critical, use the // SugaredLogger. It's 4-10x faster than other structured logging packages and @@ -41,14 +41,15 @@ // variadic number of key-value pairs. (For more advanced use cases, they also // accept strongly typed fields - see the SugaredLogger.With documentation for // details.) -// sugar := zap.NewExample().Sugar() -// defer sugar.Sync() -// sugar.Infow("failed to fetch URL", -// "url", "http://example.com", -// "attempt", 3, -// "backoff", time.Second, -// ) -// sugar.Infof("failed to fetch URL: %s", "http://example.com") +// +// sugar := zap.NewExample().Sugar() +// defer sugar.Sync() +// sugar.Infow("failed to fetch URL", +// "url", "http://example.com", +// "attempt", 3, +// "backoff", time.Second, +// ) +// sugar.Infof("failed to fetch URL: %s", "http://example.com") // // By default, loggers are unbuffered. However, since zap's low-level APIs // allow buffering, calling Sync before letting your process exit is a good @@ -57,32 +58,35 @@ // In the rare contexts where every microsecond and every allocation matter, // use the Logger. It's even faster than the SugaredLogger and allocates far // less, but it only supports strongly-typed, structured logging. -// logger := zap.NewExample() -// defer logger.Sync() -// logger.Info("failed to fetch URL", -// zap.String("url", "http://example.com"), -// zap.Int("attempt", 3), -// zap.Duration("backoff", time.Second), -// ) +// +// logger := zap.NewExample() +// defer logger.Sync() +// logger.Info("failed to fetch URL", +// zap.String("url", "http://example.com"), +// zap.Int("attempt", 3), +// zap.Duration("backoff", time.Second), +// ) // // Choosing between the Logger and SugaredLogger doesn't need to be an // application-wide decision: converting between the two is simple and // inexpensive. -// logger := zap.NewExample() -// defer logger.Sync() -// sugar := logger.Sugar() -// plain := sugar.Desugar() // -// Configuring Zap +// logger := zap.NewExample() +// defer logger.Sync() +// sugar := logger.Sugar() +// plain := sugar.Desugar() +// +// # Configuring Zap // // The simplest way to build a Logger is to use zap's opinionated presets: // NewExample, NewProduction, and NewDevelopment. These presets build a logger // with a single function call: -// logger, err := zap.NewProduction() -// if err != nil { -// log.Fatalf("can't initialize zap logger: %v", err) -// } -// defer logger.Sync() +// +// logger, err := zap.NewProduction() +// if err != nil { +// log.Fatalf("can't initialize zap logger: %v", err) +// } +// defer logger.Sync() // // Presets are fine for small projects, but larger projects and organizations // naturally require a bit more customization. For most users, zap's Config @@ -94,7 +98,7 @@ // go.uber.org/zap/zapcore. See the package-level AdvancedConfiguration // example for sample code. // -// Extending Zap +// # Extending Zap // // The zap package itself is a relatively thin wrapper around the interfaces // in go.uber.org/zap/zapcore. Extending zap to support a new encoding (e.g., @@ -106,7 +110,7 @@ // Similarly, package authors can use the high-performance Encoder and Core // implementations in the zapcore package to build their own loggers. // -// Frequently Asked Questions +// # Frequently Asked Questions // // An FAQ covering everything from installation errors to design decisions is // available at https://github.com/uber-go/zap/blob/master/FAQ.md. diff --git a/http_handler.go b/http_handler.go index d3a271c7d..632b6831a 100644 --- a/http_handler.go +++ b/http_handler.go @@ -33,22 +33,23 @@ import ( // ServeHTTP is a simple JSON endpoint that can report on or change the current // logging level. // -// GET +// # GET // // The GET request returns a JSON description of the current logging level like: -// {"level":"info"} // -// PUT +// {"level":"info"} +// +// # PUT // // The PUT request changes the logging level. It is perfectly safe to change the // logging level while a program is running. Two content types are supported: // -// Content-Type: application/x-www-form-urlencoded +// Content-Type: application/x-www-form-urlencoded // // With this content type, the level can be provided through the request body or // a query parameter. The log level is URL encoded like: // -// level=debug +// level=debug // // The request body takes precedence over the query parameter, if both are // specified. @@ -56,18 +57,17 @@ import ( // This content type is the default for a curl PUT request. Following are two // example curl requests that both set the logging level to debug. // -// curl -X PUT localhost:8080/log/level?level=debug -// curl -X PUT localhost:8080/log/level -d level=debug +// curl -X PUT localhost:8080/log/level?level=debug +// curl -X PUT localhost:8080/log/level -d level=debug // // For any other content type, the payload is expected to be JSON encoded and // look like: // -// {"level":"info"} +// {"level":"info"} // // An example curl request could look like this: // -// curl -X PUT localhost:8080/log/level -H "Content-Type: application/json" -d '{"level":"debug"}' -// +// curl -X PUT localhost:8080/log/level -H "Content-Type: application/json" -d '{"level":"debug"}' func (lvl AtomicLevel) ServeHTTP(w http.ResponseWriter, r *http.Request) { type errorResponse struct { Error string `json:"error"` diff --git a/logger.go b/logger.go index 33c9f2c8c..b5f9a99fd 100644 --- a/logger.go +++ b/logger.go @@ -111,7 +111,7 @@ func NewDevelopment(options ...Option) (*Logger, error) { // and panics if the error is non-nil. It is intended for use in variable // initialization such as: // -// var logger = zap.Must(zap.NewProduction()) +// var logger = zap.Must(zap.NewProduction()) func Must(logger *Logger, err error) *Logger { if err != nil { panic(err) diff --git a/options.go b/options.go index e2028df70..1511166c0 100644 --- a/options.go +++ b/options.go @@ -145,7 +145,7 @@ func OnFatal(action zapcore.CheckWriteAction) Option { // goroutine after writing a fatal log message, but it will not exit the // program. // -// zap.New(core, zap.WithFatalHook(zapcore.WriteThenGoexit)) +// zap.New(core, zap.WithFatalHook(zapcore.WriteThenGoexit)) // // It is important that the provided CheckWriteHook stops the control flow at // the current statement to meet expectations of callers of the logger. diff --git a/sugar.go b/sugar.go index 01351b603..c450b2dda 100644 --- a/sugar.go +++ b/sugar.go @@ -40,17 +40,17 @@ const ( // Unlike the Logger, the SugaredLogger doesn't insist on structured logging. // For each log level, it exposes four methods: // -// - methods named after the log level for log.Print-style logging -// - methods ending in "w" for loosely-typed structured logging -// - methods ending in "f" for log.Printf-style logging -// - methods ending in "ln" for log.Println-style logging +// - methods named after the log level for log.Print-style logging +// - methods ending in "w" for loosely-typed structured logging +// - methods ending in "f" for log.Printf-style logging +// - methods ending in "ln" for log.Println-style logging // // For example, the methods for InfoLevel are: // -// Info(...any) Print-style logging -// Infow(...any) Structured logging (read as "info with") -// Infof(string, ...any) Printf-style logging -// Infoln(...any) Println-style logging +// Info(...any) Print-style logging +// Infow(...any) Structured logging (read as "info with") +// Infof(string, ...any) Printf-style logging +// Infoln(...any) Println-style logging type SugaredLogger struct { base *Logger } @@ -86,21 +86,24 @@ func (s *SugaredLogger) WithOptions(opts ...Option) *SugaredLogger { // and the second as the field value. // // For example, -// sugaredLogger.With( -// "hello", "world", -// "failure", errors.New("oh no"), -// Stack(), -// "count", 42, -// "user", User{Name: "alice"}, -// ) +// +// sugaredLogger.With( +// "hello", "world", +// "failure", errors.New("oh no"), +// Stack(), +// "count", 42, +// "user", User{Name: "alice"}, +// ) +// // is the equivalent of -// unsugared.With( -// String("hello", "world"), -// String("failure", "oh no"), -// Stack(), -// Int("count", 42), -// Object("user", User{Name: "alice"}), -// ) +// +// unsugared.With( +// String("hello", "world"), +// String("failure", "oh no"), +// Stack(), +// Int("count", 42), +// Object("user", User{Name: "alice"}), +// ) // // Note that the keys in key-value pairs should be strings. In development, // passing a non-string key panics. In production, the logger is more @@ -187,7 +190,8 @@ func (s *SugaredLogger) Fatalf(template string, args ...interface{}) { // pairs are treated as they are in With. // // When debug-level logging is disabled, this is much faster than -// s.With(keysAndValues).Debug(msg) +// +// s.With(keysAndValues).Debug(msg) func (s *SugaredLogger) Debugw(msg string, keysAndValues ...interface{}) { s.log(DebugLevel, msg, nil, keysAndValues) } diff --git a/zapcore/buffered_write_syncer.go b/zapcore/buffered_write_syncer.go index 4cbc75454..a40e93b3e 100644 --- a/zapcore/buffered_write_syncer.go +++ b/zapcore/buffered_write_syncer.go @@ -49,17 +49,17 @@ const ( // BufferedWriteSyncer, and defer a Stop() call for when you no longer need the // object. // -// func main() { -// ws := ... // your log destination -// bws := &zapcore.BufferedWriteSyncer{WS: ws} -// defer bws.Stop() +// func main() { +// ws := ... // your log destination +// bws := &zapcore.BufferedWriteSyncer{WS: ws} +// defer bws.Stop() // -// // ... -// core := zapcore.NewCore(enc, bws, lvl) -// logger := zap.New(core) +// // ... +// core := zapcore.NewCore(enc, bws, lvl) +// logger := zap.New(core) // -// // ... -// } +// // ... +// } // // By default, a BufferedWriteSyncer will buffer up to 256 kilobytes of logs, // waiting at most 30 seconds between flushes. @@ -68,12 +68,12 @@ const ( // For example, the following buffers up to 512 kB of logs before flushing them // to Stderr, with a maximum of one minute between each flush. // -// ws := &BufferedWriteSyncer{ -// WS: os.Stderr, -// Size: 512 * 1024, // 512 kB -// FlushInterval: time.Minute, -// } -// defer ws.Stop() +// ws := &BufferedWriteSyncer{ +// WS: os.Stderr, +// Size: 512 * 1024, // 512 kB +// FlushInterval: time.Minute, +// } +// defer ws.Stop() type BufferedWriteSyncer struct { // WS is the WriteSyncer around which BufferedWriteSyncer will buffer // writes. diff --git a/zapcore/encoder.go b/zapcore/encoder.go index 6e5fd5651..5769ff3e4 100644 --- a/zapcore/encoder.go +++ b/zapcore/encoder.go @@ -188,10 +188,13 @@ func (e *TimeEncoder) UnmarshalText(text []byte) error { // UnmarshalYAML unmarshals YAML to a TimeEncoder. // If value is an object with a "layout" field, it will be unmarshaled to TimeEncoder with given layout. -// timeEncoder: -// layout: 06/01/02 03:04pm +// +// timeEncoder: +// layout: 06/01/02 03:04pm +// // If value is string, it uses UnmarshalText. -// timeEncoder: iso8601 +// +// timeEncoder: iso8601 func (e *TimeEncoder) UnmarshalYAML(unmarshal func(interface{}) error) error { var o struct { Layout string `json:"layout" yaml:"layout"` diff --git a/zapcore/entry.go b/zapcore/entry.go index 76eea2822..ea0431eb3 100644 --- a/zapcore/entry.go +++ b/zapcore/entry.go @@ -156,10 +156,10 @@ type Entry struct { // // Register one on a CheckedEntry with the After method. // -// if ce := logger.Check(...); ce != nil { -// ce = ce.After(hook) -// ce.Write(...) -// } +// if ce := logger.Check(...); ce != nil { +// ce = ce.After(hook) +// ce.Write(...) +// } // // You can configure the hook for Fatal log statements at the logger level with // the zap.WithFatalHook option. diff --git a/zapcore/error.go b/zapcore/error.go index 74919b0cc..06359907a 100644 --- a/zapcore/error.go +++ b/zapcore/error.go @@ -36,13 +36,13 @@ import ( // causer (from github.com/pkg/errors), a ${key}Causes field is added with an // array of objects containing the errors this error was comprised of. // -// { -// "error": err.Error(), -// "errorVerbose": fmt.Sprintf("%+v", err), -// "errorCauses": [ -// ... -// ], -// } +// { +// "error": err.Error(), +// "errorVerbose": fmt.Sprintf("%+v", err), +// "errorCauses": [ +// ... +// ], +// } func encodeError(key string, err error, enc ObjectEncoder) (retErr error) { // Try to capture panics (from nil references or otherwise) when calling // the Error() method diff --git a/zapcore/json_encoder.go b/zapcore/json_encoder.go index c5d751b82..3921c5cd3 100644 --- a/zapcore/json_encoder.go +++ b/zapcore/json_encoder.go @@ -71,7 +71,9 @@ type jsonEncoder struct { // // Note that the encoder doesn't deduplicate keys, so it's possible to produce // a message like -// {"foo":"bar","foo":"baz"} +// +// {"foo":"bar","foo":"baz"} +// // This is permitted by the JSON specification, but not encouraged. Many // libraries will ignore duplicate key-value pairs (typically keeping the last // pair) when unmarshaling, but users should attempt to avoid adding duplicate diff --git a/zapcore/sampler.go b/zapcore/sampler.go index 8c116049d..a15b7c910 100644 --- a/zapcore/sampler.go +++ b/zapcore/sampler.go @@ -113,12 +113,12 @@ func nopSamplingHook(Entry, SamplingDecision) {} // This hook may be used to get visibility into the performance of the sampler. // For example, use it to track metrics of dropped versus sampled logs. // -// var dropped atomic.Int64 -// zapcore.SamplerHook(func(ent zapcore.Entry, dec zapcore.SamplingDecision) { -// if dec&zapcore.LogDropped > 0 { -// dropped.Inc() -// } -// }) +// var dropped atomic.Int64 +// zapcore.SamplerHook(func(ent zapcore.Entry, dec zapcore.SamplingDecision) { +// if dec&zapcore.LogDropped > 0 { +// dropped.Inc() +// } +// }) func SamplerHook(hook func(entry Entry, dec SamplingDecision)) SamplerOption { return optionFunc(func(s *sampler) { s.hook = hook @@ -135,7 +135,7 @@ func SamplerHook(hook func(entry Entry, dec SamplingDecision)) SamplerOption { // // For example, // -// core = NewSamplerWithOptions(core, time.Second, 10, 5) +// core = NewSamplerWithOptions(core, time.Second, 10, 5) // // This will log the first 10 log entries with the same level and message // in a one second interval as-is. Following that, it will allow through diff --git a/zapio/writer.go b/zapio/writer.go index 05da32b38..9ac2e95a8 100644 --- a/zapio/writer.go +++ b/zapio/writer.go @@ -36,15 +36,15 @@ import ( // and you want to log the output using your existing logger configuration. For // example, // -// writer := &zapio.Writer{Log: logger, Level: zap.DebugLevel} -// defer writer.Close() +// writer := &zapio.Writer{Log: logger, Level: zap.DebugLevel} +// defer writer.Close() // -// cmd := exec.CommandContext(ctx, ...) -// cmd.Stdout = writer -// cmd.Stderr = writer -// if err := cmd.Run(); err != nil { -// return err -// } +// cmd := exec.CommandContext(ctx, ...) +// cmd.Stdout = writer +// cmd.Stderr = writer +// if err := cmd.Run(); err != nil { +// return err +// } // // Writer must be closed when finished to flush buffered data to the logger. type Writer struct { diff --git a/zaptest/logger.go b/zaptest/logger.go index 1e2451c26..6a4a35497 100644 --- a/zaptest/logger.go +++ b/zaptest/logger.go @@ -61,7 +61,7 @@ func WrapOptions(zapOpts ...zap.Option) LoggerOption { // NewLogger builds a new Logger that logs all messages to the given // testing.TB. // -// logger := zaptest.NewLogger(t) +// logger := zaptest.NewLogger(t) // // Use this with a *testing.T or *testing.B to get logs which get printed only // if a test fails or if you ran go test -v. @@ -69,11 +69,11 @@ func WrapOptions(zapOpts ...zap.Option) LoggerOption { // The returned logger defaults to logging debug level messages and above. // This may be changed by passing a zaptest.Level during construction. // -// logger := zaptest.NewLogger(t, zaptest.Level(zap.WarnLevel)) +// logger := zaptest.NewLogger(t, zaptest.Level(zap.WarnLevel)) // // You may also pass zap.Option's to customize test logger. // -// logger := zaptest.NewLogger(t, zaptest.WrapOptions(zap.AddCaller())) +// logger := zaptest.NewLogger(t, zaptest.WrapOptions(zap.AddCaller())) func NewLogger(t TestingT, opts ...LoggerOption) *zap.Logger { cfg := loggerOptions{ Level: zapcore.DebugLevel,