zapcore/BufferedWriteSyncer: More docs

[abhinav]

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.

[codecov]

Codecov Report

Merging #1139 (bf4b557) into master (4cfaabd) will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##           master    #1139   +/-   ##
=======================================
  Coverage   98.22%   98.22%           
=======================================
  Files          49       49           
  Lines        2146     2146           
=======================================
  Hits         2108     2108           
  Misses         29       29           
  Partials        9        9           

Impacted Files	Coverage Δ
zapcore/buffered_write_syncer.go	100.00% <ø> (ø)

Help us with your feedback. Take ten seconds to tell us how you rate us.

[sywhang]

👍

[joni-jones]

Thanks @abhinav for the documentation.

I'd like to make a few suggestions.

As documentation for BufferedWriteSyncer wasn't there, I was researching its usage on my own.
This is how I implemented it.

var cfg zap.Config
var enc zapcore.Encoder
cfg = zap.NewProductionConfig()
enc = zapcore.NewJSONEncoder(cfg.EncoderConfig)
sink, closeOut, err := zap.Open(cfg.OutputPaths...)
if err != nil {
    _, err = fmt.Fprintf(os.Stderr, "Could not get log Output paths." + err.Error())
}
errSink, _, err := zap.Open(cfg.ErrorOutputPaths...)
if err != nil {
    _, err = fmt.Fprintf(os.Stderr, "Could not get log Error Output paths." + err.Error())
    closeOut()
}

ws := &zapcore.BufferedWriteSyncer{WS: sink}
Logger = zap.New(
    zapcore.NewCore(enc, ws, cfg.Level),
    BuildOptions(cfg, errSink)...,
)

I still want to use standard lockedWriteSyncer but wrapped by BufferedWriteSyncer, so the logs will be written only when the buffer is full or after a specified period of time.

As, Config.openSinks and Config.buildOptions are not available for the client code, I had to mimic Config.openSinks behavior and completely copy Config.buildOptions. Is there a better way to do it?