errors: update documentation

errors/doc.go

@@ -4,10 +4,12 @@ Package errors implements custom error interfaces for weave.
 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.
-Unless an error is very specific for an extension (ie ErrInvalidSequence in
-x/sigs) it can be registered outside of 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:
+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")
 
@@ -24,6 +26,10 @@ information by using Wrap function, for example:
 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