From 8a14570ba81f296eadd64b421918c9683c5a6817 Mon Sep 17 00:00:00 2001
From: Abhinav Gupta <mail@abhinavg.net>
Date: Sun, 17 Sep 2023 15:11:40 -0700
Subject: [PATCH] doc: Clarify contract for primitive encoders (#1360)

Clarify that custom primitive encoders for
level, time, duration, and caller
must make *exactly* one call to a `Append*` method
on the PrimitiveArrayEncoder provided.

Refs #1359
---
 zapcore/encoder.go | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/zapcore/encoder.go b/zapcore/encoder.go
index 5769ff3e4..044625415 100644
--- a/zapcore/encoder.go
+++ b/zapcore/encoder.go
@@ -37,6 +37,9 @@ const DefaultLineEnding = "\n"
 const OmitKey = ""
 
 // A LevelEncoder serializes a Level to a primitive type.
+//
+// This function must make exactly one call
+// to a PrimitiveArrayEncoder's Append* method.
 type LevelEncoder func(Level, PrimitiveArrayEncoder)
 
 // LowercaseLevelEncoder serializes a Level to a lowercase string. For example,
@@ -90,6 +93,9 @@ func (e *LevelEncoder) UnmarshalText(text []byte) error {
 }
 
 // A TimeEncoder serializes a time.Time to a primitive type.
+//
+// This function must make exactly one call
+// to a PrimitiveArrayEncoder's Append* method.
 type TimeEncoder func(time.Time, PrimitiveArrayEncoder)
 
 // EpochTimeEncoder serializes a time.Time to a floating-point number of seconds
@@ -219,6 +225,9 @@ func (e *TimeEncoder) UnmarshalJSON(data []byte) error {
 }
 
 // A DurationEncoder serializes a time.Duration to a primitive type.
+//
+// This function must make exactly one call
+// to a PrimitiveArrayEncoder's Append* method.
 type DurationEncoder func(time.Duration, PrimitiveArrayEncoder)
 
 // SecondsDurationEncoder serializes a time.Duration to a floating-point number of seconds elapsed.
@@ -262,6 +271,9 @@ func (e *DurationEncoder) UnmarshalText(text []byte) error {
 }
 
 // A CallerEncoder serializes an EntryCaller to a primitive type.
+//
+// This function must make exactly one call
+// to a PrimitiveArrayEncoder's Append* method.
 type CallerEncoder func(EntryCaller, PrimitiveArrayEncoder)
 
 // FullCallerEncoder serializes a caller in /full/path/to/package/file:line
@@ -292,6 +304,9 @@ func (e *CallerEncoder) UnmarshalText(text []byte) error {
 
 // A NameEncoder serializes a period-separated logger name to a primitive
 // type.
+//
+// This function must make exactly one call
+// to a PrimitiveArrayEncoder's Append* method.
 type NameEncoder func(string, PrimitiveArrayEncoder)
 
 // FullNameEncoder serializes the logger name as-is.