From 39aa3a14588751bdf91fc777a1a45473a7bdba5e Mon Sep 17 00:00:00 2001
From: Prashant Varanasi <prashant@uber.com>
Date: Thu, 11 Jun 2020 11:01:28 -0700
Subject: [PATCH] Document when ObjectMarshaler and ArrayMarshaler are used
 (#837)

Fixes #836
---
 zapcore/marshaler.go | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/zapcore/marshaler.go b/zapcore/marshaler.go
index 2627a653d..c3c55ba0d 100644
--- a/zapcore/marshaler.go
+++ b/zapcore/marshaler.go
@@ -23,6 +23,10 @@ package zapcore
 // ObjectMarshaler allows user-defined types to efficiently add themselves to the
 // logging context, and to selectively omit information which shouldn't be
 // included in logs (e.g., passwords).
+//
+// Note: ObjectMarshaler is only used when zap.Object is used or when
+// passed directly to zap.Any. It is not used when reflection-based
+// encoding is used.
 type ObjectMarshaler interface {
 	MarshalLogObject(ObjectEncoder) error
 }
@@ -39,6 +43,10 @@ func (f ObjectMarshalerFunc) MarshalLogObject(enc ObjectEncoder) error {
 // ArrayMarshaler allows user-defined types to efficiently add themselves to the
 // logging context, and to selectively omit information which shouldn't be
 // included in logs (e.g., passwords).
+//
+// Note: ArrayMarshaler is only used when zap.Array is used or when
+// passed directly to zap.Any. It is not used when reflection-based
+// encoding is used.
 type ArrayMarshaler interface {
 	MarshalLogArray(ArrayEncoder) error
 }