fix dogoc comments

Author: PeterIvanov

error.go

@@ -6,9 +6,9 @@ import (
 	"strings"
 )
 
-// An instance of error
-// At the moment of creation, Error collects information based on context, creation modifiers and type it belongs to
-// Error is mostly immutable, and distinct errors composition is achieved through wrap
+// Error is an instance of error object,
+// At the moment of creation, Error collects information based on context, creation modifiers and type it belongs to.
+// Error is mostly immutable, and distinct errors composition is achieved through wrap.
 type Error struct {
 	message     string
 	errorType   *Type
@@ -21,10 +21,10 @@ type Error struct {
 
 var _ fmt.Formatter = (*Error)(nil)
 
-// Add a dynamic property to error instance
-// If an error already contained another value for the same property, it is overwritten
-// It is a caller's responsibility to accumulate and update a property, if needed
-// Dynamic properties is a brittle mechanism and should therefore be used with care and in a simple and robust manner
+// WithProperty adds a dynamic property to error instance.
+// If an error already contained another value for the same property, it is overwritten.
+// It is a caller's responsibility to accumulate and update a property, if needed.
+// Dynamic properties is a brittle mechanism and should therefore be used with care and in a simple and robust manner.
 func (e *Error) WithProperty(key Property, value interface{}) *Error {
 	if e.properties == nil {
 		e.properties = make(map[Property]interface{}, 1)
@@ -34,9 +34,9 @@ func (e *Error) WithProperty(key Property, value interface{}) *Error {
 	return e
 }
 
-// Adds multiple additional related (hidden, suppressed) errors to be used exclusively in error output
-// Note that these errors make no other effect whatsoever: their traits, types, properties etc. are lost on the observer
-// Consider using errorx.DecorateMany instead
+// WithUnderlyingErrors adds multiple additional related (hidden, suppressed) errors to be used exclusively in error output.
+// Note that these errors make no other effect whatsoever: their traits, types, properties etc. are lost on the observer.
+// Consider using errorx.DecorateMany instead.
 func (e *Error) WithUnderlyingErrors(errs ...error) *Error {
 	for _, err := range errs {
 		if err == nil {
@@ -49,10 +49,10 @@ func (e *Error) WithUnderlyingErrors(errs ...error) *Error {
 	return e
 }
 
-// Extract a dynamic property value from an error
-// A property may belong to this error, or be extracted from the original cause
+// Property extracts a dynamic property value from an error.
+// 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
+// may have accessible properties, but an opaque wrapper hides the original properties.
 func (e *Error) Property(key Property) (interface{}, bool) {
 	cause := e
 	for cause != nil {
@@ -71,10 +71,10 @@ func (e *Error) Property(key Property) (interface{}, bool) {
 	return nil, false
 }
 
-// Check 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
-// 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.
+// 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.
+// 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
 	for cause != nil {
@@ -89,9 +89,9 @@ func (e *Error) HasTrait(key Trait) bool {
 	return false
 }
 
-// A proper type check for an error
+// IsOfType is a proper type check for an error.
 // It takes the transparency and error types hierarchy into account,
-// so that type check against any supertype of the original cause passes
+// so that type check against any supertype of the original cause passes.
 func (e *Error) IsOfType(t *Type) bool {
 	cause := e
 	for cause != nil {
@@ -105,12 +105,12 @@ func (e *Error) IsOfType(t *Type) bool {
 	return false
 }
 
-// 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
+// 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.
 func (e *Error) Type() *Type {
 	cause := e
 	for cause != nil {
@@ -124,27 +124,27 @@ func (e *Error) Type() *Type {
 	return foreignType
 }
 
-// Returns a message of this particular error, disregarding the cause
-// The result of this method, like a result of an Error() method, should never be used to infer the meaning of an error
-// In most cases, message is only used as a part of formatting to print error contents into a log file
-// Manual extraction may be required, however, to transform an error into another format - say, API response
+// Message returns a message of this particular error, disregarding the cause.
+// The result of this method, like a result of an Error() method, should never be used to infer the meaning of an error.
+// In most cases, message is only used as a part of formatting to print error contents into a log file.
+// Manual extraction may be required, however, to transform an error into another format - say, API response.
 func (e *Error) Message() string {
 	return e.message
 }
 
-// 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
-// This method is, therefore, reserved for system utilities, not for general use
+// 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.
+// This method is, therefore, reserved for system utilities, not for general use.
 func (e *Error) Cause() error {
 	return e.cause
 }
 
-// Implements the Formatter interface
-// Supports %v or %s for simple message output, and %+v for 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
+// Format implements the Formatter interface.
+// Supports %v or %s for simple message output, and %+v for 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.
 func (e *Error) Format(s fmt.State, verb rune) {
 	message := e.fullMessage()
 	switch verb {
@@ -158,8 +158,8 @@ func (e *Error) Format(s fmt.State, verb rune) {
 	}
 }
 
-// Implements the error interface
-// A result is the same as with %s formatter and does not contain a stack trace
+// Error implements the error interface.
+// A result is the same as with %s formatter and does not contain a stack trace.
 func (e *Error) Error() string {
 	return e.fullMessage()
 }