fix dogoc comments

Author: PeterIvanov

panic.go

@@ -2,15 +2,16 @@ package errorx
 
 import "fmt"
 
-// When calling panic as a reaction to error, prefer this function over vanilla panic()
+// Panic is an alternative to the built-in panic call.
+// When calling panic as a reaction to error, prefer this function over vanilla panic().
 // If err happens to be an errorx error, it may hold the original stack trace of the issue.
-// With panic(err), this information may be lost if panic is handled by the default handler
+// With panic(err), this information may be lost if panic is handled by the default handler.
 // With errorx.Panic(err), all data is preserved regardless of the handle mechanism.
-// It can be recovered either from default panic message, recover() result or ErrorFromPanic() function
+// It can be recovered either from default panic message, recover() result or ErrorFromPanic() function.
 //
 // Even if err stack trace is exactly the same as default panic trace, this can be tolerated,
 // 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
+// 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)
@@ -19,15 +20,15 @@ func Panic(err error) error {
 	panic(newPanicErrorWrapper(err))
 }
 
-// Recover the original error from panic, best employed along with Panic() function from the same package.
+// ErrorFromPanic recovers the original error from panic, best employed along with Panic() function from the same package.
 // The original error, if present, typically holds more relevant data
-// than a combination of panic message and the stack trace which can be collected after recover()
+// than a combination of panic message and the stack trace which can be collected after recover().
 //
 // More importantly, it allows for greater composability,
-// if ever there is a need to recover from panic and pass the error information forwards in its proper form
+// if ever there is a need to recover from panic and pass the error information forwards in its proper form.
 //
 // Note that panic is not a proper means to report errors,
-// so this mechanism should never be used where a error based control flow is at all possible
+// so this mechanism should never be used where a error based control flow is at all possible.
 func ErrorFromPanic(recoverResult interface{}) (error, bool) {
 	err, ok := recoverResult.(error)
 	if !ok {

property.go

@@ -4,36 +4,36 @@ import (
 	"context"
 )
 
-// Key to a dynamic property of an error
-// Property value belongs to an error instance only, never inherited from a type
-// Property visibility is hindered by Wrap, preserved by Decorate
+// Property is a key to a dynamic property of an error.
+// Property value belongs to an error instance only, never inherited from a type.
+// Property visibility is hindered by Wrap, preserved by Decorate.
 type Property struct {
 	id    int64
 	label string
 }
 
-// Register a new property key
-// It is used both to add a dynamic property to an error instance, and to extract property value back from error
+// RegisterProperty registers a new property key.
+// It is used both to add a dynamic property to an error instance, and to extract property value back from error.
 func RegisterProperty(label string) Property {
 	return newProperty(label)
 }
 
-// Context property, value is expected to be of context.Context type
+// Context property, value is expected to be of context.Context type.
 func PropertyContext() Property {
 	return propertyContext
 }
 
-// Payload property, value may contain user defined structure with arbitrary data passed along with an error
+// Payload property, value may contain user defined structure with arbitrary data passed along with an error.
 func PropertyPayload() Property {
 	return propertyPayload
 }
 
-// A statically typed helper to add a context property to an error
+// WithContext is a statically typed helper to add a context property to an error.
 func WithContext(err *Error, ctx context.Context) *Error {
 	return err.WithProperty(PropertyContext(), ctx)
 }
 
-// A statically typed helper to extract a context property from an error
+// ExtractContext is a statically typed helper to extract a context property from an error.
 func ExtractContext(err error) (context.Context, bool) {
 	rawCtx, ok := ExtractProperty(err, PropertyContext())
 	if !ok {
@@ -43,18 +43,18 @@ func ExtractContext(err error) (context.Context, bool) {
 	return rawCtx.(context.Context), true
 }
 
-// A helper to add a payload property to an error
+// WithPayload is a helper to add a payload property to an error.
 func WithPayload(err *Error, payload interface{}) *Error {
 	return err.WithProperty(PropertyPayload(), payload)
 }
 
-// Helper to add a payload property to an error
+// ExtractPayload is a helper to extract a payload property from an error.
 func ExtractPayload(err error) (interface{}, bool) {
 	return ExtractProperty(err, PropertyPayload())
 }
 
-// Attempt to extract a property value by a provided key
-// A property may belong to this error, or be extracted from the original cause
+// 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.
 func ExtractProperty(err error, key Property) (interface{}, bool) {
 	typedErr := Cast(err)
 	if typedErr == nil {

registry.go

@@ -2,19 +2,19 @@ package errorx
 
 import "sync"
 
-// An interface to receive callbacks on the registered error namespaces and types
-// This may be used to create a user-defined registry, for example, to check if all type names are unique
-// ISSUE: if .ApplyModifiers is called for a type/namespace, callback still receives a value without those modifiers
+// TypeSubscriber is an interface to receive callbacks on the registered error namespaces and types.
+// This may be used to create a user-defined registry, for example, to check if all type names are unique.
+// ISSUE: if .ApplyModifiers is called for a type/namespace, callback still receives a value without those modifiers.
 type TypeSubscriber interface {
 	// Method is called exactly once for each namespace
 	OnNamespaceCreated(namespace Namespace)
 	// Method is called exactly once for each type
 	OnTypeCreated(t *Type)
 }
 
-// Add a new TypeSubscriber
-// A subscriber is guaranteed to receive callbacks for all namespaces and types
-// If a type is already registered at the moment of subscription, a callback for this type is called immediately
+// RegisterTypeSubscriber adds a new TypeSubscriber.
+// A subscriber is guaranteed to receive callbacks for all namespaces and types.
+// If a type is already registered at the moment of subscription, a callback for this type is called immediately.
 func RegisterTypeSubscriber(s TypeSubscriber) {
 	globalRegistry.registerTypeSubscriber(s)
 }

stacktrace.go

@@ -12,13 +12,13 @@ import (
 // A used defined transformer for file path in stack trace output
 type StackTraceFilePathTransformer func(string) string
 
-// Provide a transformer to be used in formatting of all the errors
-// It is OK to leave it alone, stack trace will retain its exact original information
-// This feature may be beneficial, however, if a shortening of file path will make it more convenient to use
-// One of such examples is to transform a project-related path from absolute to relative and thus more IDE-friendly
+// InitializeStackTraceTransformer provides a transformer to be used in formatting of all the errors.
+// It is OK to leave it alone, stack trace will retain its exact original information.
+// This feature may be beneficial, however, if a shortening of file path will make it more convenient to use.
+// One of such examples is to transform a project-related path from absolute to relative and thus more IDE-friendly.
 //
-// NB: error is returned if a transformer was already registered
-// Transformer is changed nonetheless, the old one is returned along with an error
+// NB: error is returned if a transformer was already registered.
+// Transformer is changed nonetheless, the old one is returned along with an error.
 // User is at liberty to either ignore it, panic, reinstate the old transformer etc.
 func InitializeStackTraceTransformer(transformer StackTraceFilePathTransformer) (StackTraceFilePathTransformer, error) {
 	stackTraceTransformer.mu.Lock()

switch.go

@@ -12,12 +12,12 @@ var (
 	caseNoTrait = RegisterTrait("synthetic.no.trait")
 )
 
-// Used to perform a switch around the type of an error
-// For nil errors, returns nil
-// 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
+// TypeSwitch is used to perform a switch around the type of an error.
+// For nil errors, returns nil.
+// 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.
 func TypeSwitch(err error, types ...*Type) *Type {
 	typed := Cast(err)
 
@@ -37,12 +37,12 @@ func TypeSwitch(err error, types ...*Type) *Type {
 	}
 }
 
-// Used to perform a switch around the trait of an error
-// For nil errors, returns CaseNoError()
-// 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
+// TraitSwitch is used to perform a switch around the trait of an error.
+// For nil errors, returns CaseNoError().
+// 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.
 func TraitSwitch(err error, traits ...Trait) Trait {
 	typed := Cast(err)
 

trait.go

@@ -1,22 +1,22 @@
 package errorx
 
-// Trait is a static characteristic of an error type
-// All errors of a specific type possess exactly the same traits
-// Traits are both defined along with an error and inherited from a supertype and a namespace
+// Trait is a static characteristic of an error type.
+// All errors of a specific type possess exactly the same traits.
+// Traits are both defined along with an error and inherited from a supertype and a namespace.
 type Trait struct {
 	id    int64
 	label string
 }
 
-// Declare a new distinct traits
-// Traits are matched exactly, distinct traits are considered separate event if they have the same label
+// RegisterTrait declares a new distinct traits.
+// Traits are matched exactly, distinct traits are considered separate event if they have the same label.
 func RegisterTrait(label string) Trait {
 	return newTrait(label)
 }
 
-// Check 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
-// This alternative is preferable, though, as it is less brittle and generally creates less of a dependency
+// 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.
+// 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)
 	if typedErr == nil {
@@ -26,34 +26,34 @@ func HasTrait(err error, key Trait) bool {
 	return typedErr.HasTrait(key)
 }
 
-// A trait that signifies that an error is temporary in nature
+// A trait that signifies that an error is temporary in nature.
 func Temporary() Trait { return traitTemporary }
 
-// A trait that signifies that an error is some sort iof timeout
+// A trait that signifies that an error is some sort iof timeout.
 func Timeout() Trait { return traitTimeout }
 
-// A trait that marks such an error where the requested object is not found
+// A trait that marks such an error where the requested object is not found.
 func NotFound() Trait { return traitNotFound }
 
-// A trait that marks such an error where an update is failed as a duplicate
+// A trait that marks such an error where an update is failed as a duplicate.
 func Duplicate() Trait { return traitDuplicate }
 
-// Check for Temporary trait
+// IsTemporary checks for Temporary trait.
 func IsTemporary(err error) bool {
 	return HasTrait(err, Temporary())
 }
 
-// Check for Timeout trait
+// IsTimeout checks for Timeout trait.
 func IsTimeout(err error) bool {
 	return HasTrait(err, Timeout())
 }
 
-// Check for NotFound trait
+// IsNotFound checks for NotFound trait.
 func IsNotFound(err error) bool {
 	return HasTrait(err, NotFound())
 }
 
-// Check for Duplicate trait
+// IsDuplicate checks for Duplicate trait.
 func IsDuplicate(err error) bool {
 	return HasTrait(err, Duplicate())
 }