Merge pull request #10 from gregwebs/docs-deprecation

update docs around deprecation

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

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 ""