review and flow the godoc according to new right margin

asisunwrap.go

@@ -5,19 +5,20 @@ import (
 	"reflect"
 )
 
-// As finds the first error in `err`'s chain that matches target, and if so, sets
-// target to that error value and returns true.
+// As finds the first error in `err`'s chain that matches target,
+// and if so, sets target to that error value and returns true.
 //
-// The chain consists of err itself followed by the sequence of errors obtained by
-// repeatedly calling Unwrap.
+// The chain consists of err itself followed by the sequence of errors
+// obtained by repeatedly calling Unwrap.
 //
-// An error matches target if the error's concrete value is assignable to the value
-// pointed to by target, or if the error has a method As(interface{}) bool such that
-// As(target) returns true. In the latter case, the As method is responsible for
-// setting target.
+// An error matches target if the error's concrete value is assignable
+// to the value pointed to by target, or if the error has a method
+// As(interface{}) bool such that As(target) returns true. In the
+// latter case, the As method is responsible for setting target.
 //
-// As will panic if target is not a non-nil pointer to either a type that implements
-// error, or to any interface type. As returns false if err is nil.
+// As will panic if target is not a non-nil pointer to either a
+// type that implements error, or to any interface type. "As"
+// returns false if err is nil.
 func As(err error, target interface{}) bool {
 	if target == nil {
 		panic("errors: target cannot be nil")
@@ -79,11 +80,12 @@ var errorType = reflect.TypeOf((*error)(nil)).Elem()
 
 // Is reports whether any error in `err`'s chain matches target.
 //
-// The chain consists of err itself followed by the sequence of errors obtained by
-// repeatedly calling Unwrap.
+// The chain consists of err itself followed by the sequence of
+// errors obtained by repeatedly calling Unwrap.
 //
-// An error is considered to match a target if it is equal to that target or if
-// it implements a method Is(error) bool such that Is(target) returns true.
+// An error is considered to match a target if it is equal to that
+// target or if it implements a method Is(error) bool such that
+// Is(target) returns true.
 func Is(err, target error) bool {
 	if target == nil {
 		return err == target

causes.go

@@ -64,7 +64,9 @@ func (w *causes2) Defer(err *error) {
 // WithStackInfo.Attach() can only wrap and hold one child error object.
 //
 // WithErrors attach child errors into an error container.
-// For a container which has IsEmpty() interface, it would not be attach if it is empty (i.e. no errors).
+// For a container which has IsEmpty() interface, it would not
+// be attached if it is empty (i.e. no errors).
+//
 // For a nil error object, it will be ignored.
 func (w *causes2) WithErrors(errs ...error) *causes2 {
 	if len(errs) > 0 {
@@ -248,8 +250,8 @@ func (w *causes2) TypeIs(target error) bool {
 	return TypeIsSlice(w.Causers, target)
 }
 
-// As finds the first error in `err`'s chain that matches target, and if so, sets
-// target to that error value and returns true.
+// As finds the first error in `err`'s chain that matches target,
+// and if so, sets target to that error value and returns true.
 func (w *causes2) As(target interface{}) bool {
 	if c, ok := target.(*Code); ok {
 		*c = w.Code

coded.go

@@ -18,28 +18,28 @@ const (
 	Unknown Code = -2
 
 	// InvalidArgument indicates client specified an invalid argument.
-	// Note that this differs from FailedPrecondition. It indicates arguments
-	// that are problematic regardless of the state of the system
-	// (e.g., a malformed file name).
+	// Note that this differs from FailedPrecondition. It indicates
+	// arguments that are problematic regardless of the state of the
+	// system (e.g., a malformed file name).
 	InvalidArgument Code = -3
 
 	// DeadlineExceeded means operation expired before completion.
-	// For operations that change the state of the system, this error may be
-	// returned even if the operation has completed successfully. For
-	// example, a successful response from a server could have been delayed
-	// long enough for the deadline to expire.
+	// For operations that change the state of the system, this error
+	// might be returned even if the operation has completed
+	// successfully. For example, a successful response from a server
+	// could have been delayed long enough for the deadline to expire.
 	//
 	// = HTTP 408 Timeout
 	DeadlineExceeded Code = -4
 
-	// NotFound means some requested entity (e.g., file or directory) was
-	// not found.
+	// NotFound means some requested entity (e.g., file or directory)
+	// wasn't found.
 	//
 	// = HTTP 404
 	NotFound Code = -5
 
-	// AlreadyExists means an attempt to create an entity failed because one
-	// already exists.
+	// AlreadyExists means an attempt to create an entity failed
+	// because one already exists.
 	AlreadyExists Code = -6
 
 	// PermissionDenied indicates the caller does not have permission to
@@ -50,8 +50,9 @@ const (
 	// instead for those errors).
 	PermissionDenied Code = -7
 
-	// ResourceExhausted indicates some resource has been exhausted, perhaps
-	// a per-user quota, or perhaps the entire file system is out of space.
+	// ResourceExhausted indicates some resource has been exhausted,
+	// perhaps a per-user quota, or perhaps the entire file system
+	// is out of space.
 	ResourceExhausted Code = -8
 
 	// FailedPrecondition indicates operation was rejected because the
@@ -111,8 +112,8 @@ const (
 
 	// Unavailable indicates the service is currently unavailable.
 	// This is a most likely a transient condition and may be corrected
-	// by retrying with a backoff. Note that it is not always safe to retry
-	// non-idempotent operations.
+	// by retrying with a backoff. Note that it is not always safe to
+	// retry non-idempotent operations.
 	//
 	// See litmus test above for deciding between FailedPrecondition,
 	// Aborted, and Unavailable.
@@ -127,15 +128,19 @@ const (
 	// = HTTP 401 Unauthorized
 	Unauthenticated Code = -16
 
-	// RateLimited indicates some flow control algorithm is running and applied.
+	// RateLimited indicates some flow control algorithm is running
+	// and applied.
+	//
 	// = HTTP Code 429
 	RateLimited Code = -17
 
 	// BadRequest generates a 400 error.
+	//
 	// = HTTP 400
 	BadRequest Code = -18
 
 	// Conflict generates a 409 error.
+	//
 	// = hTTP 409
 	Conflict Code = -19
 

def.go

@@ -6,7 +6,8 @@ type Error interface {
 	Buildable
 
 	// Data returns the wrapped common user data by Buildable.WithData.
-	// The error objects with passed Buildable.WithData will be moved
+	//
+	// The error objects with a passed Buildable.WithData will be moved
 	// into inner errors set, so its are excluded from Data().
 	Data() []interface{}
 	// TaggedData returns the wrapped tagged user data by
@@ -86,7 +87,9 @@ type Buildable interface {
 	// StackTrace of errs will be copied to callee so that you can get a
 	// trace output nearer by the last error.
 	//
-	// defer-recover block typically is a better place of WithData(). For example:
+	// defer-recover block typically is a better place of WithData().
+	//
+	// For example:
 	//
 	//    defer func() {
 	//      if e := recover(); e != nil {
@@ -105,7 +108,8 @@ type Buildable interface {
 	// WithCause sets the underlying error manually if necessary.
 	WithCause(cause error) Buildable
 
-	// End could terminate the with-build stream calls without any return value.
+	// End could terminate the with-build stream calls without any
+	// returned value.
 	End()
 
 	// Container _
@@ -200,8 +204,8 @@ type Container interface {
 type Attachable interface {
 	// Attach collects the errors except it's nil
 	//
-	// StackTrace of errs will be copied to callee so that you can get a
-	// trace output nearer by the last error.
+	// StackTrace of errs will be copied to callee so that you can
+	// get a trace output nearer by the last error.
 	//
 	Attach(errs ...error)
 }

doc.go

@@ -2,7 +2,8 @@
  * Copyright © 2019 Hedzr Yeh.
  */
 
-// Package errors provides some error handling primitives for wrapped, coded, messaged errors.
+// Package errors provides some error handling primitives for
+// wrapped, coded, messaged errors.
 //
 package errors
 

errors.go

@@ -4,6 +4,15 @@ import "fmt"
 
 // New returns an error with the supplied message.
 // New also records the Stack trace at the point where it was called.
+//
+// New supports two kind of args: an Opt option or a message format
+// with variadic args.
+//
+// Sample 1:
+//    var err = errors.New("message here: %s", "hello")
+// Sample 2:
+//    var err = errors.New(errors.WithErrors(errs...))
+//    var err = errors.New(errors.WithStack(cause))
 func New(args ...interface{}) Error {
 	s := &builder{skip: 1}
 
@@ -26,15 +35,18 @@ func New(args ...interface{}) Error {
 type Opt func(s *builder)
 
 // WithErrors attach child errors into an error container.
-// For a container which has IsEmpty() interface, it would not be attach if it is empty (i.e. no errors).
+// For a container which has IsEmpty() interface, it would not be
+// attached if it is empty (i.e. no errors).
 // For a nil error object, it will be ignored.
+//
 func WithErrors(errs ...error) Opt {
 	return func(s *builder) {
 		s.WithErrors(errs...)
 	}
 }
 
-// Skip sets how many frames will be ignored while we are extracting the stacktrace info.
+// Skip sets how many frames will be ignored while we are extracting
+// the stacktrace info.
 // Skip starts a builder with fluent API style, so you could continue
 // build the error what you want:
 //
@@ -44,7 +56,8 @@ func Skip(skip int) Builder {
 	return &builder{skip: skip}
 }
 
-// Message formats a message and starts a builder to create the final error object.
+// Message formats a message and starts a builder to create the final
+// error object.
 //
 //     err := errors.Message("hello %v", "you").Attach(causer).Build()
 func Message(message string, args ...interface{}) Builder {
@@ -66,21 +79,25 @@ func NewBuilder() Builder {
 	return &builder{skip: 1}
 }
 
-// Builder provides a fluent calling interface to make error building easy.
+// Builder provides a fluent calling interface to make error
+// building easy.
 type Builder interface {
 
-	// WithSkip specifies a special number of stack frames that will be ignored.
+	// WithSkip specifies a special number of stack frames that will
+	// be ignored.
 	WithSkip(skip int) Builder
 	// WithErrors attaches the given errs as inner errors.
-	// For a container which has IsEmpty() interface, it would not be attach if it is empty (i.e. no errors).
+	// For a container which has IsEmpty() interface, it would not
+	// be attached if it is empty (i.e. no errors).
 	// For a nil error object, it will be ignored.
 	WithErrors(errs ...error) Builder
 	// WithMessage formats the error message
 	WithMessage(message string, args ...interface{}) Builder
 	// WithCode specifies an error code.
 	WithCode(code Code) Builder
 
-	// Build builds the final error object (with Buildable interface bound)
+	// Build builds the final error object (with Buildable interface
+	// bound)
 	Build() Error
 
 	// BREAK - Use WithErrors() for instead
@@ -95,7 +112,8 @@ type builder struct {
 	taggedSites TaggedData
 }
 
-// WithSkip specifies a special number of stack frames that will be ignored.
+// WithSkip specifies a special number of stack frames that will
+// be ignored.
 func (s *builder) WithSkip(skip int) Builder {
 	s.skip = skip
 	return s
@@ -123,7 +141,8 @@ func (s *builder) WithMessage(message string, args ...interface{}) Builder {
 }
 
 // WithErrors attaches the given errs as inner errors.
-// For a container which has IsEmpty() interface, it would not be attach if it is empty (i.e. no errors).
+// For a container which has IsEmpty() interface, it would not
+// be attached if it is empty (i.e. no errors).
 // For a nil error object, it will be ignored.
 func (s *builder) WithErrors(errs ...error) Builder {
 	_ = s.causes2.WithErrors(errs...)

stack.go

@@ -46,7 +46,8 @@ func (f Frame) line() int {
 //
 // Format accepts flags that alter the printing of some verbs, as follows:
 //
-//    %+s   function name and path of source file relative to the compile time
+//    %+s   function name and path of source file relative to the
+//          compiling time.
 //          GOPATH separated by \n\t (<funcname>\n\t<path>)
 //    %+v   equivalent to %+s:%d
 func (f Frame) Format(s fmt.State, verb rune) {

tool.go

@@ -4,7 +4,8 @@ import (
 	"runtime"
 )
 
-// DumpStacksAsString returns stack tracing information like debug.PrintStack()
+// DumpStacksAsString returns stack tracing information like
+// debug.PrintStack()
 func DumpStacksAsString(allRoutines bool) string {
 	buf := make([]byte, 16384)
 	buf = buf[:runtime.Stack(buf, allRoutines)]

withstackinfo.go

@@ -22,7 +22,9 @@ func (w *WithStackInfo) IsDescended(descendant error) bool {
 	return false
 }
 
-// WithStack annotates err with a Stack trace at the point WithStack was called.
+// WithStack annotates err with a Stack trace at the point WithStack
+// was called.
+//
 // If err is nil, WithStack returns nil.
 func WithStack(cause error) error {
 	if cause == nil {
@@ -36,11 +38,12 @@ func WithStack(cause error) error {
 // For instance, the construction of an error without warnings looks like:
 //
 //      err := New("hello %v", "world")
-//      _ = err.WithErrors(io.EOF, io.ErrShortWrite).
+//      _ = err.
+//          WithErrors(io.EOF, io.ErrShortWrite).
 //          WithErrors(io.ErrClosedPipe).
 //          WithCode(Internal)
 //
-// To avoid the `_ =`, you might belove with a End() call:
+// To avoid the `_ =`, you might beloved with a End() call:
 //
 //      err := New("hello %v", "world")
 //      err.WithErrors(io.EOF, io.ErrShortWrite).
@@ -78,7 +81,8 @@ func (w *WithStackInfo) rebuild() Buildable {
 	return w
 }
 
-// WithSkip specifies a special number of stack frames that will be ignored.
+// WithSkip specifies a special number of stack frames that will
+// be ignored.
 func (w *WithStackInfo) WithSkip(skip int) Buildable {
 	w.Stack = callers(skip)
 	return w
@@ -147,7 +151,9 @@ func (w *WithStackInfo) WithErrors(errs ...error) Buildable {
 // StackTrace of errs will be copied to callee so that you can get a
 // trace output nearer by the last error.
 //
-// defer-recover block typically is a better place of WithData(). For example:
+// defer-recover block typically is a better place of WithData().
+//
+// For example:
 //
 //    defer func() {
 //      if e := recover(); e != nil {
@@ -245,8 +251,8 @@ func (w *WithStackInfo) Clone() *WithStackInfo {
 
 // Format formats the stack of Frames according to the fmt.Formatter interface.
 //
-//    %s	lists source files for each Frame in the stack
-//    %v	lists the source file and line number for each Frame in the stack
+//    %s   lists source files for each Frame in the stack
+//    %v   lists the source file and line number for each Frame in the stack
 //
 // Format accepts flags that alter the printing of some verbs, as follows:
 //