From ca232b973d5025a9fab2e2ea460a00c605161418 Mon Sep 17 00:00:00 2001
From: Abhinav Gupta <abg@uber.com>
Date: Mon, 1 Aug 2022 15:24:07 -0700
Subject: [PATCH] zapcore/BufferedWriteSyncer: More docs (#1139)

Better document how to use BufferedWriteSyncer in a real application.

Highlight that a `Stop()` method call should be deferred,
and how to change the default parameters of a BufferedWriteSyncer.
---
 zapcore/buffered_write_syncer.go | 31 +++++++++++++++++++++++++++++++
 1 file changed, 31 insertions(+)

diff --git a/zapcore/buffered_write_syncer.go b/zapcore/buffered_write_syncer.go
index ef2f7d963..4cbc75454 100644
--- a/zapcore/buffered_write_syncer.go
+++ b/zapcore/buffered_write_syncer.go
@@ -43,6 +43,37 @@ const (
 //
 // BufferedWriteSyncer is safe for concurrent use. You don't need to use
 // zapcore.Lock for WriteSyncers with BufferedWriteSyncer.
+//
+// To set up a BufferedWriteSyncer, construct a WriteSyncer for your log
+// destination (*os.File is a valid WriteSyncer), wrap it with
+// 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()
+//
+//     // ...
+//     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.
+// You can customize these parameters by setting the Size or FlushInterval
+// fields.
+// 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()
 type BufferedWriteSyncer struct {
 	// WS is the WriteSyncer around which BufferedWriteSyncer will buffer
 	// writes.