examples

Author: PeterIvanov

builder.go

@@ -6,8 +6,8 @@ import (
 )
 
 // ErrorBuilder is a utility to compose an error from type.
-// Typically, a direct usage is not required: either Type methods of helpers like Decorate is sufficient.
-// Only use builder if no neater alternative is available.
+// Typically, a direct usage is not required: either Type methods of helpers like Decorate are sufficient.
+// Only use builder if no simpler alternative is available.
 type ErrorBuilder struct {
 	errorType     *Type
 	message       string

error.go

@@ -50,7 +50,7 @@ func (e *Error) WithUnderlyingErrors(errs ...error) *Error {
 }
 
 // Property extracts a dynamic property value from an error.
-// A property may belong to this error, or be extracted from the original cause.
+// A property may belong to this error or be extracted from the original cause.
 // The transparency rules are respected to some extent: both the original cause and the transparent wrapper
 // may have accessible properties, but an opaque wrapper hides the original properties.
 func (e *Error) Property(key Property) (interface{}, bool) {
@@ -73,7 +73,7 @@ func (e *Error) Property(key Property) (interface{}, bool) {
 
 // HasTrait checks if an error possesses the expected trait.
 // Trait check works just as a type check would: opaque wrap hides the traits of the cause.
-// Traits are always a property of a type rather than of an instance, so trait check is an alternative to a type check.
+// Traits are always properties of a type rather than of an instance, so trait check is an alternative to a type check.
 // This alternative is preferable, though, as it is less brittle and generally creates less of a dependency.
 func (e *Error) HasTrait(key Trait) bool {
 	cause := e
@@ -108,6 +108,7 @@ func (e *Error) IsOfType(t *Type) bool {
 // Type returns the exact type of this error.
 // With transparent wrapping, such as in Decorate(), returns the type of the original cause.
 // The result is always not nil, even if the resulting type is impossible to successfully type check against.
+//
 // NB: the exact error type may fail an equality check where a IsOfType() check would succeed.
 // This may happen if a type is checked against one of its supertypes, for example.
 // Therefore, handle direct type checks with care or avoid it altogether and use TypeSwitch() or IsForType() instead.
@@ -135,7 +136,7 @@ func (e *Error) Message() string {
 // Cause returns the immediate (wrapped) cause of current error.
 // This method could be used to dig for root cause of the error, but it is not advised to do so.
 // Errors should not require a complex navigation through causes to be properly handled, and the need to do so is a code smell.
-// Manually extracting cause defeats features such as properties of wrap, behaviour of properties etc.
+// Manually extracting cause defeats features such as opaque wrap, behaviour of properties etc.
 // This method is, therefore, reserved for system utilities, not for general use.
 func (e *Error) Cause() error {
 	return e.cause
@@ -145,8 +146,8 @@ func (e *Error) Cause() error {
 // Supported verbs:
 //
 // 		%s		simple message output
-// 		%v 		same as %s
-// 		%+v 	full output complete with a stack trace
+// 		%v		same as %s
+// 		%+v		full output complete with a stack trace
 //
 // In is nearly always preferable to use %+v format.
 // If a stack trace is not required, it should be omitted at the moment of creation rather in formatting.

example_test.go

@@ -76,11 +76,11 @@ func ExampleError_Format() {
 	//
 	//Error full: common.assertion_failed: example
 	// at github.com/joomcode/errorx_test.someFunc()
-	//	/Users/p.ivanov/go/src/github.com/joomcode/errorx/example_test.go:102
+	//	/Users/username/go/src/github.com/joomcode/errorx/example_test.go:102
 	// at github.com/joomcode/errorx_test.nestedCall()
-	//	/Users/p.ivanov/go/src/github.com/joomcode/errorx/example_test.go:98
+	//	/Users/username/go/src/github.com/joomcode/errorx/example_test.go:98
 	// at github.com/joomcode/errorx_test.ExampleError_Format()
-	//	/Users/p.ivanov/go/src/github.com/joomcode/errorx/example_test.go:66
+	//	/Users/username/go/src/github.com/joomcode/errorx/example_test.go:66
 	// <...> more
 }
 
@@ -97,7 +97,7 @@ func ExampleEnhanceStackTrace() {
 	// Example output:
 	//Error full: another goroutine, cause: common.assertion_failed: example
 	// at github.com/joomcode/errorx_test.ExampleEnhanceStackTrace()
-	//	/Users/p.ivanov/go/src/github.com/joomcode/errorx/example_test.go:94
+	//	/Users/username/go/src/github.com/joomcode/errorx/example_test.go:94
 	// at testing.runExample()
 	//	/usr/local/Cellar/go/1.10.3/libexec/src/testing/example.go:122
 	// at testing.runExamples()
@@ -110,11 +110,11 @@ func ExampleEnhanceStackTrace() {
 	// (1 duplicated frames)
 	// ----------------------------------
 	// at github.com/joomcode/errorx_test.someFunc()
-	//	/Users/p.ivanov/go/src/github.com/joomcode/errorx/example_test.go:106
+	//	/Users/username/go/src/github.com/joomcode/errorx/example_test.go:106
 	// at github.com/joomcode/errorx_test.nestedCall()
-	//	/Users/p.ivanov/go/src/github.com/joomcode/errorx/example_test.go:102
+	//	/Users/username/go/src/github.com/joomcode/errorx/example_test.go:102
 	// at github.com/joomcode/errorx_test.ExampleEnhanceStackTrace.func1()
-	//	/Users/p.ivanov/go/src/github.com/joomcode/errorx/example_test.go:90
+	//	/Users/username/go/src/github.com/joomcode/errorx/example_test.go:90
 	// at runtime.goexit()
 	//	/usr/local/Cellar/go/1.10.3/libexec/src/runtime/asm_amd64.s:2361
 }

panic.go

@@ -13,9 +13,11 @@ import "fmt"
 // as panics must not be a way to report conventional errors and are therefore rare.
 // With this in mind, it is better to err on the side of completeness rather than brevity.
 //
-// This function never returns, but the signature may be convenient, i.e.:
-// * return nil, errorx.Panic(err)
-// * panic(errorx.Panic(err))
+// This function never returns, but the signature may be used for convenience:
+//
+// 		return nil, errorx.Panic(err)
+// 		panic(errorx.Panic(err))
+//
 func Panic(err error) error {
 	panic(newPanicErrorWrapper(err))
 }

property.go

@@ -54,7 +54,7 @@ func ExtractPayload(err error) (interface{}, bool) {
 }
 
 // ExtractProperty attempts to extract a property value by a provided key.
-// A property may belong to this error, or be extracted from the original cause.
+// A property may belong to this error or be extracted from the original cause.
 func ExtractProperty(err error, key Property) (interface{}, bool) {
 	typedErr := Cast(err)
 	if typedErr == nil {

stackframe.go

@@ -10,10 +10,10 @@ type frame interface {
 	Line() int
 }
 
-type FrameHelper struct {
+type frameHelper struct {
 }
 
-var frameHelper = &FrameHelper{}
+var frameHelperSingleton = &frameHelper{}
 
 type defaultFrame struct {
 	frame *runtime.Frame
@@ -31,7 +31,7 @@ func (f *defaultFrame) Line() int {
 	return f.frame.Line
 }
 
-func (c *FrameHelper) GetFrames(pcs []uintptr) []frame {
+func (c *frameHelper) GetFrames(pcs []uintptr) []frame {
 	frames := runtime.CallersFrames(pcs[:])
 	result := make([]frame, 0, len(pcs))
 

stacktrace.go

@@ -101,7 +101,7 @@ func (st *stackTrace) formatStackTrace(s fmt.State) {
 		return
 	}
 
-	frames := frameHelper.GetFrames(pc)
+	frames := frameHelperSingleton.GetFrames(pc)
 	for _, frame := range frames {
 		io.WriteString(s, "\n at ")
 		io.WriteString(s, frame.Function())

switch.go

@@ -17,7 +17,8 @@ var (
 // For error types not in the 'types' list, including non-errorx errors, NotRecognisedType() is returned.
 // It is safe to treat NotRecognisedType() as 'any other type of not-nil error' case.
 // The effect is equivalent to a series of IsOfType() checks.
-// NB: if more than one provided types matches with error, the first match in the providers list is recognised.
+//
+// NB: if more than one provided types matches the error, the first match in the providers list is recognised.
 func TypeSwitch(err error, types ...*Type) *Type {
 	typed := Cast(err)
 
@@ -42,7 +43,8 @@ func TypeSwitch(err error, types ...*Type) *Type {
 // For error types that lack any of the provided traits, including non-errorx errors, CaseNoTrait() is returned.
 // It is safe to treat CaseNoTrait() as 'any other kind of not-nil error' case.
 // The effect is equivalent to a series of HasTrait() checks.
-// NB: if more than one provided types matches with error, the first match in the providers list is recognised.
+
+// NB: if more than one provided types matches the error, the first match in the providers list is recognised.
 func TraitSwitch(err error, traits ...Trait) Trait {
 	typed := Cast(err)
 

trait.go

@@ -15,7 +15,7 @@ func RegisterTrait(label string) Trait {
 }
 
 // HasTrait checks if an error possesses the expected trait.
-// Traits are always a property of a type rather than of an instance, so trait check is an alternative to a type check.
+// Traits are always properties of a type rather than of an instance, so trait check is an alternative to a type check.
 // This alternative is preferable, though, as it is less brittle and generally creates less of a dependency.
 func HasTrait(err error, key Trait) bool {
 	typedErr := Cast(err)

type.go

@@ -74,7 +74,7 @@ func (t *Type) WrapWithNoMessage(err error) *Error {
 }
 
 // IsOfType is a type check for error.
-// Returns true either both are exactly the same type, or if the same is true for one of current type's ancestors.
+// Returns true either if both are of exactly the same type, or if the same is true for one of current type's ancestors.
 func (t *Type) IsOfType(other *Type) bool {
 	current := t
 	for current != nil {
@@ -89,7 +89,7 @@ func (t *Type) IsOfType(other *Type) bool {
 }
 
 // IsOfType is a type check for errors.
-// Returns true either both are exactly the same type, or if the same is true for one of current type's ancestors.
+// Returns true either if both are of exactly the same type, or if the same is true for one of current type's ancestors.
 // For an error that does not have an errorx type, returns false.
 func IsOfType(err error, t *Type) bool {
 	e := Cast(err)