From 017f38e9e2a4ad0df849a2795ceb3b644d04fdf1 Mon Sep 17 00:00:00 2001
From: Greg Weber <greg@gregweber.info>
Date: Wed, 19 Sep 2018 20:56:23 -0700
Subject: [PATCH] update docs around deprecation

---
 errors.go       | 17 ++++++++++-------
 juju_adaptor.go |  7 +++++--
 2 files changed, 15 insertions(+), 9 deletions(-)

diff --git a/errors.go b/errors.go
index 4e2e967..2e1d3f6 100644
--- a/errors.go
+++ b/errors.go
@@ -152,7 +152,8 @@ func (f *fundamental) Format(s fmt.State, verb rune) {
 // WithStack annotates err with a stack trace at the point WithStack was called.
 // If err is nil, WithStack returns nil.
 //
-// Deprecated: use AddStack
+// For most use cases this is deprecated and AddStack should be used (which will ensure just one stack trace).
+// However, one may want to use this in some situations, for example to create a 2nd trace across a goroutine.
 func WithStack(err error) error {
 	if err == nil {
 		return nil
@@ -197,10 +198,11 @@ func (w *withStack) Format(s fmt.State, verb rune) {
 }
 
 // Wrap returns an error annotating err with a stack trace
-// at the point Annotate is called, and the supplied message.
-// If err is nil, Annotate returns nil.
+// at the point Wrap is called, and the supplied message.
+// If err is nil, Wrap returns nil.
 //
-// Deprecated: use Annotate instead
+// For most use cases this is deprecated in favor of Annotate.
+// Annotate avoids creating duplicate stack traces.
 func Wrap(err error, message string) error {
 	if err == nil {
 		return nil
@@ -218,10 +220,11 @@ func Wrap(err error, message string) error {
 }
 
 // Wrapf returns an error annotating err with a stack trace
-// at the point Annotatef is call, and the format specifier.
-// If err is nil, Annotatef returns nil.
+// at the point Wrapf is call, and the format specifier.
+// If err is nil, Wrapf returns nil.
 //
-// Deprecated: use Annotatef instead
+// For most use cases this is deprecated in favor of Annotatef.
+// Annotatef avoids creating duplicate stack traces.
 func Wrapf(err error, format string, args ...interface{}) error {
 	if err == nil {
 		return nil
diff --git a/juju_adaptor.go b/juju_adaptor.go
index 773a197..0b20f57 100644
--- a/juju_adaptor.go
+++ b/juju_adaptor.go
@@ -6,12 +6,12 @@ import (
 
 // ==================== juju adaptor start ========================
 
-// Trace annotates err with a stack trace at the point WithStack was called.
-// If err is nil or already contain stack trace return directly.
+// Trace just calls AddStack.
 func Trace(err error) error {
 	return AddStack(err)
 }
 
+// Annotate adds a message and ensures there is a stack trace.
 func Annotate(err error, message string) error {
 	if err == nil {
 		return nil
@@ -31,6 +31,7 @@ func Annotate(err error, message string) error {
 	}
 }
 
+// Annotatef adds a message and ensures there is a stack trace.
 func Annotatef(err error, format string, args ...interface{}) error {
 	if err == nil {
 		return nil
@@ -51,6 +52,8 @@ func Annotatef(err error, format string, args ...interface{}) error {
 }
 
 // ErrorStack will format a stack trace if it is available, otherwise it will be Error()
+// If the error is nil, the empty string is returned
+// Note that this just calls fmt.Sprintf("%+v", err)
 func ErrorStack(err error) string {
 	if err == nil {
 		return ""