From 46339da83a8e0a8aa7a0341950df866c8bbf26e8 Mon Sep 17 00:00:00 2001
From: Olivier Poitrey <rs@rhapsodyk.net>
Date: Sat, 12 Aug 2017 16:16:31 -0700
Subject: [PATCH] Improve doc for WithContext

---
 ctx.go | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

diff --git a/ctx.go b/ctx.go
index 034eccd..6157e29 100644
--- a/ctx.go
+++ b/ctx.go
@@ -9,7 +9,15 @@ var disabledLogger = New(ioutil.Discard).Level(Disabled)
 
 type ctxKey struct{}
 
-// WithContext returns a copy of ctx with l associated.
+// WithContext returns a copy of ctx with l associated. If an instance of Logger
+// is already in the context, the pointer to this logger is updated with l.
+//
+// For instance, to add a field to an existing logger in the context, use this
+// notation:
+//
+//     ctx := r.Context()
+//     l := zerolog.Ctx(ctx)
+//     ctx = l.With().Str("foo", "bar").WithContext(ctx)
 func (l Logger) WithContext(ctx context.Context) context.Context {
 	if lp, ok := ctx.Value(ctxKey{}).(*Logger); ok {
 		// Update existing pointer.