doc: New{Production,Development}Encoder{,Config} (#1234)

Better document the specifics of the following functions:

- NewDevelopmentConfig
- NewDevelopmentEncoderConfig
- NewProductionConfig
- NewProductionEncoderConfig

This gives users the information they need to understand the default
behavior without digging into the implementation.

Refs #1129

config.go

@@ -95,6 +95,32 @@ type Config struct {
 
 // NewProductionEncoderConfig returns an opinionated EncoderConfig for
 // production environments.
+//
+// Messages encoded with this configuration will be JSON-formatted
+// and will have the following keys by default:
+//
+//   - "level": The logging level (e.g. "info", "error").
+//   - "ts": The current time in number of seconds since the Unix epoch.
+//   - "msg": The message passed to the log statement.
+//   - "caller": If available, a short path to the file and line number
+//     where the log statement was issued.
+//     The logger configuration determines whether this field is captured.
+//   - "stacktrace": If available, a stack trace from the line
+//     where the log statement was issued.
+//     The logger configuration determines whether this field is captured.
+//
+// By default, the following formats are used for different types:
+//
+//   - Time is formatted as floating-point number of seconds since the Unix
+//     epoch.
+//   - Duration is formatted as floating-point number of seconds.
+//
+// You may change these by setting the appropriate fields in the returned
+// object.
+// For example, use the following to change the time encoding format:
+//
+//	cfg := zap.NewProductionEncoderConfig()
+//	cfg.EncodeTime = zapcore.ISO8601TimeEncoder
 func NewProductionEncoderConfig() zapcore.EncoderConfig {
 	return zapcore.EncoderConfig{
 		TimeKey:        "ts",
@@ -112,11 +138,22 @@ func NewProductionEncoderConfig() zapcore.EncoderConfig {
 	}
 }
 
-// NewProductionConfig is a reasonable production logging configuration.
-// Logging is enabled at InfoLevel and above.
+// NewProductionConfig builds a reasonable default production logging
+// configuration.
+// Logging is enabled at InfoLevel and above, and uses a JSON encoder.
+// Logs are written to standard error.
+// Stacktraces are included on logs of ErrorLevel and above.
+// DPanicLevel logs will not panic, but will write a stacktrace.
+//
+// Sampling is enabled at 100:100 by default,
+// meaning that after the first 100 log entries
+// with the same level and message in the same second,
+// it will log every 100th entry
+// with the same level and message in the same second.
+// You may disable this behavior by setting Sampling to nil.
 //
-// It uses a JSON encoder, writes to standard error, and enables sampling.
-// Stacktraces are automatically included on logs of ErrorLevel and above.
+// See [NewProductionEncoderConfig] for information
+// on the default encoder configuration.
 func NewProductionConfig() Config {
 	return Config{
 		Level:       NewAtomicLevelAt(InfoLevel),
@@ -134,6 +171,32 @@ func NewProductionConfig() Config {
 
 // NewDevelopmentEncoderConfig returns an opinionated EncoderConfig for
 // development environments.
+//
+// Messages encoded with this configuration will use Zap's console encoder
+// intended to print human-readable output.
+// It will print log messages with the following information:
+//
+//   - The log level (e.g. "INFO", "ERROR").
+//   - The time in ISO8601 format (e.g. "2017-01-01T12:00:00Z").
+//   - The message passed to the log statement.
+//   - If available, a short path to the file and line number
+//     where the log statement was issued.
+//     The logger configuration determines whether this field is captured.
+//   - If available, a stacktrace from the line
+//     where the log statement was issued.
+//     The logger configuration determines whether this field is captured.
+//
+// By default, the following formats are used for different types:
+//
+//   - Time is formatted in ISO8601 format (e.g. "2017-01-01T12:00:00Z").
+//   - Duration is formatted as a string (e.g. "1.234s").
+//
+// You may change these by setting the appropriate fields in the returned
+// object.
+// For example, use the following to change the time encoding format:
+//
+//	cfg := zap.NewDevelopmentEncoderConfig()
+//	cfg.EncodeTime = zapcore.ISO8601TimeEncoder
 func NewDevelopmentEncoderConfig() zapcore.EncoderConfig {
 	return zapcore.EncoderConfig{
 		// Keys can be anything except the empty string.
@@ -152,12 +215,15 @@ func NewDevelopmentEncoderConfig() zapcore.EncoderConfig {
 	}
 }
 
-// NewDevelopmentConfig is a reasonable development logging configuration.
-// Logging is enabled at DebugLevel and above.
+// NewDevelopmentConfig builds a reasonable default development logging
+// configuration.
+// Logging is enabled at DebugLevel and above, and uses a console encoder.
+// Logs are written to standard error.
+// Stacktraces are included on logs of WarnLevel and above.
+// DPanicLevel logs will panic.
 //
-// It enables development mode (which makes DPanicLevel logs panic), uses a
-// console encoder, writes to standard error, and disables sampling.
-// Stacktraces are automatically included on logs of WarnLevel and above.
+// See [NewDevelopmentEncoderConfig] for information
+// on the default encoder configuration.
 func NewDevelopmentConfig() Config {
 	return Config{
 		Level:            NewAtomicLevelAt(DebugLevel),