errors: update documentation

errors/abci.go

@@ -7,9 +7,9 @@ import (
 )
 
 const (
-	// ABCI response use 0 to signal that the processing was successful and
-	// no error is returned.
-	successABCICode = 0
+	// SuccessABCICode declares an ABCI response use 0 to signal that the
+	// processing was successful and no error is returned.
+	SuccessABCICode = 0
 
 	// All unclassified errors that do not provide an ABCI code are clubbed
 	// under an internal error code and a generic message instead of
@@ -27,7 +27,7 @@ const (
 // without an ABCICode information as considered internal.
 func ABCIInfo(err error, debug bool) (uint32, string) {
 	if errIsNil(err) {
-		return successABCICode, ""
+		return SuccessABCICode, ""
 	}
 
 	// Only non-internal errors information can be exposed. Any error that
@@ -56,7 +56,7 @@ func ABCIInfo(err error, debug bool) (uint32, string) {
 // and unwraps the error.
 func abciCode(err error) uint32 {
 	if errIsNil(err) {
-		return successABCICode
+		return SuccessABCICode
 	}
 
 	type coder interface {

errors/doc.go

@@ -1,30 +1,35 @@
 /*
 Package errors implements custom error interfaces for weave.
 
-The idea is to reuse as many errors from this package as possible and define custom package
-errors when absolutely necessary. It is best to define a new error here if you feel it's going to
-be somewhat package-agnostic.
-
-x/multisig is a good package to take a look at in terms of usage with predefined strings with/without formatting.
-x/validators and x/sigs define some custom errors.
-
-If you want to register a custom error - use Register(code, description).
-For reusing errors - use Errxxx.New and Errxxx.Newf.
-Code stands for ABCI error code, which allows to distinguish types of errors
-on the client side and act accordingly.
-
-There is also support for stacktraces. Please ensure you create the custom error using
-ErrXyz.New("...") or errors.Wrap(err, "...") at the point of creation to ensure we attach
-a stacktrace. If you wrap multiple times, we only record the first wrap with the stacktrace.
-(And don't do this as a global `var ErrFoo = errors.ErrNotFound.New("foo")` or you will get a
-useless stacktrace).
-
-Once you have an error, you can use `fmt.Printf/Sprintf` to get more context for the error
-	%s is just the error message
-	%+v is the full stack trace
-	%v appends a compressed [filename:line] where the error was created
-	(source is wrappedError.Format)
-Or call `err.StackTrace()` to get the raw call stack of the creation point
+Error declarations should be generic and cover broad range of cases. Each
+returned error instance can wrap a generic error declaration to provide more
+details.
+This package provides a broad range of errors declared that fits all common
+cases. If an error is very specific for an extension (ie ErrInvalidSequence in
+x/sigs) it can be registered outside of the errors package. Instead of
+registering an extension error consider registering it in the errors package.
+To create a new error istance use Register function. You must provide a unique,
+non zero error code and a short description, for example:
+
+  var ErrZeroDivision = errors.Register(9241, "zero division")
+
+When returning an error, you can attach to it an additional context
+information by using Wrap function, for example:
+
+   func safeDiv(val, div int) (int, err) {
+	   if div == 0 {
+		   return 0, errors.Wrapf(ErrZeroDivision, "cannot divide %d", val)
+	   }
+	   return val / div, nil
+   }
+
+The first time an error instance is wrapped a stacktrace is attached as well.
+Stacktrace information can be printed using %+v and %v formats.
+
+  %s  is just the error message
+  %+v is the full stack trace
+  %v  appends a compressed [filename:line] where the error was created
+
 */
 
 package errors