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

@@ -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:

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))
 }

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.

http_handler.go

@@ -33,41 +33,41 @@ 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.
 //
 // 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"`

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)

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.

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)
 }

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.

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"`

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.