fix dogoc comments

Author: PeterIvanov

type.go

@@ -4,10 +4,10 @@ import (
 	"encoding"
 )
 
-// A distinct error type
-// Belongs to a namespace, may be a descendant of another type in the same namespace
-// May contain or inherit modifiers that alter the default properties for any error of this type
-// May contain or inherit traits that all errors of this type will possess
+// Type is a distinct error type.
+// Belongs to a namespace, may be a descendant of another type in the same namespace.
+// May contain or inherit modifiers that alter the default properties for any error of this type.
+// May contain or inherit traits that all errors of this type will possess.
 type Type struct {
 	namespace Namespace
 	parent    *Type
@@ -19,62 +19,62 @@ type Type struct {
 
 var _ encoding.TextMarshaler = (*Type)(nil)
 
-// Defines a new distinct type within a namespace
+// NewType defines a new distinct type within a namespace.
 func NewType(namespace Namespace, name string, traits ...Trait) *Type {
 	return newType(namespace, nil, name, traits...)
 }
 
-// Defines a new subtype within a namespace of a parent type
+// NewSubtype defines a new subtype within a namespace of a parent type.
 func (t *Type) NewSubtype(name string, traits ...Trait) *Type {
 	return newType(t.namespace, t, name, traits...)
 }
 
-// One-time modification of defaults in error creation
+// ApplyModifiers makes a one-time modification of defaults in error creation.
 func (t *Type) ApplyModifiers(modifiers ...TypeModifier) *Type {
 	t.modifiers = t.modifiers.ReplaceWith(newTypeModifiers(modifiers...))
 	return t
 }
 
-// Create an error of this type with a message
-// Without args, leaves the original message intact, so a message may be generated or provided externally
-// With args, a formatting is performed, and it is therefore expected a format string to be constant
+// New creates an error of this type with a message.
+// Without args, leaves the original message intact, so a message may be generated or provided externally.
+// With args, a formatting is performed, and it is therefore expected a format string to be constant.
 func (t *Type) New(message string, args ...interface{}) *Error {
 	return NewErrorBuilder(t).
 		WithConditionallyFormattedMessage(message, args...).
 		Create()
 }
 
-// Create an error of this type without any message
-// May be used when other information is sufficient, such as error type and stack trace
+// NewWithNoMessage creates an error of this type without any message.
+// May be used when other information is sufficient, such as error type and stack trace.
 func (t *Type) NewWithNoMessage() *Error {
 	return NewErrorBuilder(t).
 		Create()
 }
 
-// Create an error of this type with another as original cause
-// As far as type checks are concerned, this error is the only one visible, with original present only in error message
-// The original error will, however, pass its dynamic properties
-// Without args, leaves the original message intact, so a message may be generated or provided externally
-// With args, a formatting is performed, and it is therefore expected a format string to be constant
+// Wrap creates an error of this type with another as original cause.
+// As far as type checks are concerned, this error is the only one visible, with original present only in error message.
+// The original error will, however, pass its dynamic properties.
+// Without args, leaves the original message intact, so a message may be generated or provided externally.
+// With args, a formatting is performed, and it is therefore expected a format string to be constant.
 func (t *Type) Wrap(err error, message string, args ...interface{}) *Error {
 	return NewErrorBuilder(t).
 		WithConditionallyFormattedMessage(message, args...).
 		WithCause(err).
 		Create()
 }
 
-// Create an error of this type with another as original cause and with no additional message
-// May be used when other information is sufficient, such as error type, cause and its stack trace and message
-// As far as type checks are concerned, this error is the only one visible, with original visible only in error message
-// The original error will, however, pass its dynamic properties
+// WrapWithNoMessage creates an error of this type with another as original cause and with no additional message.
+// May be used when other information is sufficient, such as error type, cause and its stack trace and message.
+// As far as type checks are concerned, this error is the only one visible, with original visible only in error message.
+// The original error will, however, pass its dynamic properties.
 func (t *Type) WrapWithNoMessage(err error) *Error {
 	return NewErrorBuilder(t).
 		WithCause(err).
 		Create()
 }
 
-// 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
+// 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.
 func (t *Type) IsOfType(other *Type) bool {
 	current := t
 	for current != nil {
@@ -88,25 +88,25 @@ func (t *Type) IsOfType(other *Type) bool {
 	return false
 }
 
-// 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
-// For an error that does not have an errorx type, returns false
+// 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.
+// For an error that does not have an errorx type, returns false.
 func IsOfType(err error, t *Type) bool {
 	e := Cast(err)
 	return e != nil && e.IsOfType(t)
 }
 
-// A parent type, if present
+// Supertype returns a parent type, if present.
 func (t *Type) Supertype() *Type {
 	return t.parent
 }
 
-// A fully qualified name if type, is not presumed to be unique, see TypeSubscriber
+// FullName returns a fully qualified name if type, is not presumed to be unique, see TypeSubscriber.
 func (t *Type) FullName() string {
 	return t.fullName
 }
 
-// A base namespace this type belongs to
+// RootNamespace returns a base namespace this type belongs to.
 func (t *Type) RootNamespace() Namespace {
 	return t.namespace
 }

utils.go

@@ -1,6 +1,6 @@
 package errorx
 
-// Attempts to cast an error to errorx Type, returns nil if cast has failed
+// Cast attempts to cast an error to errorx Type, returns nil if cast has failed.
 func Cast(err error) *Error {
 	if e, ok := err.(*Error); ok && e != nil {
 		return e
@@ -9,8 +9,8 @@ func Cast(err error) *Error {
 	return nil
 }
 
-// Returns nil if an error is of one of the provided types, returns the provided error otherwise
-// May be used if a particular error signifies a mark in control flow rather than an error to be reported to the caller
+// Ignore returns nil if an error is of one of the provided types, returns the provided error otherwise.
+// May be used if a particular error signifies a mark in control flow rather than an error to be reported to the caller.
 func Ignore(err error, types ...*Type) error {
 	if e := Cast(err); e != nil {
 		for _, t := range types {
@@ -23,8 +23,8 @@ func Ignore(err error, types ...*Type) error {
 	return err
 }
 
-// Returns nil if an error has one of the provided traits, returns the provided error otherwise
-// May be used if a particular error trait signifies a mark in control flow rather than an error to be reported to the caller
+// IgnoreWithTrait returns nil if an error has one of the provided traits, returns the provided error otherwise.
+// May be used if a particular error trait signifies a mark in control flow rather than an error to be reported to the caller.
 func IgnoreWithTrait(err error, traits ...Trait) error {
 	if e := Cast(err); e != nil {
 		for _, t := range traits {
@@ -37,8 +37,8 @@ func IgnoreWithTrait(err error, traits ...Trait) error {
 	return err
 }
 
-// Returns the full type name if an error; returns an empty string for non-errorx error
-// For decorated errors, the type of an original cause is used
+// GetTypeName returns the full type name if an error; returns an empty string for non-errorx error.
+// For decorated errors, the type of an original cause is used.
 func GetTypeName(err error) string {
 	if e := Cast(err); e != nil {
 		t := e.Type()
@@ -50,8 +50,8 @@ func GetTypeName(err error) string {
 	return ""
 }
 
-// A utility function to duplicate error N times
-// May be handy do demultiplex a single original error to a number of callers/requests
+// ReplicateError is a utility function to duplicate error N times.
+// May be handy do demultiplex a single original error to a number of callers/requests.
 func ReplicateError(err error, count int) []error {
 	result := make([]error, count)
 	for i := range result {

wrap.go

@@ -1,7 +1,7 @@
 package errorx
 
 var (
-	// most errors from this namespace are made private in order to disallow and direct type checks in the user code
+	// Most errors from this namespace are made private in order to disallow and direct type checks in the user code
 	syntheticErrors = NewNamespace("synthetic")
 
 	// Private error type for non-errors errors, used as a not-nil substitute that cannot be type-checked directly
@@ -14,10 +14,10 @@ var (
 	stackTraceWrapper = syntheticErrors.NewType("stacktrace").ApplyModifiers(TypeModifierTransparent)
 )
 
-// Pass some text info along with a message, leaving its semantics totally intact
-// An perceived type, traits and properties if the resulting error are those of the original
-// Without args, leaves the provided message intact, so a message may be generated or provided externally
-// With args, a formatting is performed, and it is therefore expected a format string to be constant
+// Decorate allows to pass some text info along with a message, leaving its semantics totally intact.
+// An perceived type, traits and properties if the resulting error are those of the original.
+// Without args, leaves the provided message intact, so a message may be generated or provided externally.
+// With args, a formatting is performed, and it is therefore expected a format string to be constant.
 func Decorate(err error, message string, args ...interface{}) *Error {
 	return NewErrorBuilder(transparentWrapper).
 		WithConditionallyFormattedMessage(message, args...).
@@ -26,9 +26,10 @@ func Decorate(err error, message string, args ...interface{}) *Error {
 		Create()
 }
 
-// Has all the properties of the Decorate() method and additionally extends the stack trace of the original message
-// Designed to be used when a original error is passed from another goroutine rather than from a direct method call
-// If, however, is it is call in the same goroutine, formatter makes some moderated effort to remove duplication
+// EnhanceStackTrace has all the properties of the Decorate() method
+// and additionally extends the stack trace of the original message.
+// Designed to be used when a original error is passed from another goroutine rather than from a direct method call.
+// If, however, is it is call in the same goroutine, formatter makes some moderated effort to remove duplication.
 func EnhanceStackTrace(err error, message string, args ...interface{}) *Error {
 	return NewErrorBuilder(transparentWrapper).
 		WithConditionallyFormattedMessage(message, args...).
@@ -38,9 +39,9 @@ func EnhanceStackTrace(err error, message string, args ...interface{}) *Error {
 		Create()
 }
 
-// Utility to ensure the stack trace is captured in provided error
-// If this is already true, it is returned unmodified
-// Otherwise, it is decorated with stack trace
+// EnsureStackTrace is a utility to ensure the stack trace is captured in provided error.
+// If this is already true, it is returned unmodified.
+// Otherwise, it is decorated with stack trace.
 func EnsureStackTrace(err error) *Error {
 	if typedErr := Cast(err); typedErr != nil && typedErr.stackTrace != nil {
 		return typedErr
@@ -54,10 +55,10 @@ func EnsureStackTrace(err error) *Error {
 		Create()
 }
 
-// Transparent wrap of multiple errors with additional message
-// If there are no errors, or all errors are nil, returns nil
-// If all errors are of the same type (for example, if there is only one), wraps them transparently
-// Otherwise, an opaque wrap is performed, that is, IsOfType checks will fail on underlying error types
+// DecorateMany performs a transparent wrap of multiple errors with additional message.
+// If there are no errors, or all errors are nil, returns nil.
+// If all errors are of the same type (for example, if there is only one), wraps them transparently.
+// Otherwise, an opaque wrap is performed, that is, IsOfType checks will fail on underlying error types.
 func DecorateMany(message string, errs ...error) error {
 	errs = ignoreEmpty(errs)
 	if len(errs) == 0 {
@@ -71,9 +72,9 @@ func DecorateMany(message string, errs ...error) error {
 	}
 }
 
-// Utility to wrap multiple errors
-// If there are no errors, or all errors are nil, returns nil
-// Otherwise, the fist error is treated as an original cause, others are added as underlying
+// WrapMany is a utility to wrap multiple errors.
+// If there are no errors, or all errors are nil, returns nil.
+// Otherwise, the fist error is treated as an original cause, others are added as underlying.
 func WrapMany(errorType *Type, message string, errs ...error) error {
 	errs = ignoreEmpty(errs)
 	if len(errs) == 0 {