doc: Clarify documentation, add example test

example_test.go

@@ -358,3 +358,16 @@ func ExampleWrapCore_wrap() {
 	// {"level":"info","msg":"doubled"}
 	// {"level":"info","msg":"doubled"}
 }
+
+func ExampleDict() {
+	logger := zap.NewExample()
+	defer logger.Sync()
+
+	logger.Info("login event",
+		zap.Dict("event",
+			zap.Int("id", 123),
+			zap.String("name", "jane"),
+			zap.String("status", "pending")))
+	// Output:
+	// {"level":"info","msg":"login event","event":{"id":123,"name":"jane","status":"pending"}}
+}

field.go

@@ -410,7 +410,8 @@ func Inline(val zapcore.ObjectMarshaler) Field {
 	}
 }
 
-// Dict constructs a field with the given key and Fields.
+// Dict constructs a field containing the provided key-value pairs.
+// It acts similar to [Object], but with the fields specified as arguments.
 func Dict(key string, val ...Field) Field {
 	return dictField(key, val)
 }