[e] improve documentation of the package

Change-Id: Ib70298392181acdea409654e9ad5c776ae1fe3ce

Author: xobotyi

e/doc.go

@@ -1,46 +1,46 @@
-// Package e provides custom error type and utilities to work with it.
+// Package e provides a custom error type with support for error chaining and
+// structured metadata fields.
 //
-// Its main type [Err] provides the ability to conveniently work with chains of
-// errors, offering methods to wrap any errors and pass metadata using fields
-// (fields.Field).
+// The main type, Err, enables convenient error wrapping and the attachment of
+// key-value metadata fields (fields.Field). Errors can be wrapped to add context
+// and enriched with fields for structured logging or diagnostics.
 //
-// Example:
-//
-//	var (
-//		ErrJsonParseFailed = e.New("JSON parse failed")
-//	)
+// Example: Wrapping errors with context
 //
+//	var ErrJSONParseFailed = e.New("JSON parse failed")
 //	var val any
 //	if err := json.Unmarshal([]byte(`["invalid", "json]`), &val); err != nil {
-//		return ErrJsonParseFailed.Wrap(err) // "JSON parse failed: unexpected end of JSON input"
+//		return ErrJSONParseFailed.Wrap(err)
+//		// Output: "JSON parse failed: unexpected end of JSON input"
 //	}
 //
-// Any incoming error can be granted the functionality of [Err] by using the
-// [From] function. Note that this is not a form of error wrapping - immediately
-// unwrapping such an error will not return the original one.
+// Example: Enriching errors with fields
+//
+//	err := e.New("operation failed").WithField("user_id", 42)
+//	// Output: "operation failed (user_id=42)"
+//
+//	err = err.Wrap(e.New("db error").WithFields(fields.F("query", "SELECT *")))
+//	// Output: "operation failed (user_id=42): db error (query=SELECT *)"
 //
-// Example:
+// Any error can be converted to an Err using the From function. This does not
+// wrap the error; unwrapping will not return the original error.
 //
 //	e.From(errors.New("error")) // "error"
 //	errors.Unwrap(e.From(errors.New("error"))) // nil
 //
-// [Err] serializes to following format:
+// The Err string format is:
 //
-//	`<error reason>[ (fields...)][: wrapped error string]`
+//	<reason> (fields...): <wrapped error string>
 //
-// In other words, arbitrary fields are always enclosed in parentheses, and the
-// wrapped error is separated with a colon and a space.
+// Fields are always enclosed in parentheses, and wrapped errors are separated by
+// a colon and space.
 //
-// Package does not provide any methods to modify existing errors, as it is
-// considered error-prone. Instead, any public method of the package that returns
-// an error - returns a new instance.
+// All methods that return errors create new instances; errors are immutable.
 //
-// Although [Err] implements methods [Err.Unwrap], [Err.Is], and [Err.As], these
-// methods are intended for internal use. These methods are marked as deprecated
-// to avoid confusion and improve developer experience. Consider using the
-// corresponding methods of the [errors] package instead.
+// Deprecated methods Unwrap, Is, and As are present for compatibility with the
+// errors package, but should not be used directly. Use the errors package
+// functions instead.
 //
-// To log a specific error, the package provides a convenience method [Log]. This
-// method creates a log entry from the specified error if it is not nil. It is
-// designed to be compatible with our logger abstraction - logger.Logger.
+// The Log function logs errors using our logger abstraction - logger.Logger,
+// extracting reason, wrapped error, and fields, logging them appropriately.
 package e

e/err.go

@@ -8,17 +8,20 @@ import (
 	"dev.gaijin.team/go/golib/fields"
 )
 
+// Err represents a custom error type that supports error chaining and structured metadata fields.
 type Err struct {
 	errs   []error
 	fields fields.List
 }
 
-// New creates new instance of Err.
+// New returns a new Err with the given reason and optional fields.
+// The returned error can be further wrapped or annotated with additional fields.
 func New(reason string, f ...fields.Field) *Err {
 	return From(errors.New(reason), f...) //nolint:err113
 }
 
-// NewFrom creates new instance of Err that wraps origin error.
+// NewFrom returns a new Err with the given reason, wrapping the provided error, and optional fields.
+// If wrapped is nil, it behaves like New.
 func NewFrom(reason string, wrapped error, f ...fields.Field) *Err {
 	if wrapped == nil {
 		return New(reason, f...)
@@ -30,9 +33,8 @@ func NewFrom(reason string, wrapped error, f ...fields.Field) *Err {
 	}
 }
 
-// From transforms existing error to Err. It is not wrapping operation - unwrap
-// will not return origin error. Passing nil to this function will result with
-// empty error.
+// From converts any error to an Err, optionally adding fields. This is not true wrapping;
+// unwrapping will not return the original error. Passing nil results in an Err with reason "error(nil)".
 func From(origin error, f ...fields.Field) *Err {
 	if origin == nil {
 		origin = errors.New("error(nil)") //nolint:err113
@@ -44,11 +46,8 @@ func From(origin error, f ...fields.Field) *Err {
 	}
 }
 
-// Wrap creates new instance of Err that wraps provided error with source one.
-//
-// Example:
-//
-//	e.New("e1").Wrap(errors.New("e2")) // e1: e2
+// Wrap returns a new Err that wraps the provided error with the current Err as context.
+// Additional fields can be attached. If err is nil, it is replaced with an Err for "error(nil)".
 func (e *Err) Wrap(err error, f ...fields.Field) *Err {
 	if err == nil {
 		err = errors.New("error(nil)") //nolint:err113
@@ -60,7 +59,7 @@ func (e *Err) Wrap(err error, f ...fields.Field) *Err {
 	}
 }
 
-// Error returns string representation of the error.
+// Error returns the string representation of the Err, including reason, fields, and wrapped errors.
 func (e *Err) Error() string {
 	b := &strings.Builder{}
 	writeTo(b, e)
@@ -96,31 +95,31 @@ func writeTo(b *strings.Builder, err error) {
 	}
 }
 
-// Clone creates a new instance of Err with the same error, wrapped error, and
-// cloned fields container.
+// Clone returns a new Err with the same error, wrapped error, and a cloned fields container.
 func (e *Err) Clone() *Err {
 	return &Err{
 		errs:   slices.Clone(e.errs),
 		fields: slices.Clone(e.fields),
 	}
 }
 
-// WithFields creates new error with source error as origin and provided fields as its fields.
+// WithFields returns a new Err with the same error and the provided fields.
 func (e *Err) WithFields(f ...fields.Field) *Err {
 	return From(e, f...)
 }
 
-// WithField alike [Err.WithFields], but creates an error with single field added.
+// WithField returns a new Err with the same error and a single additional field.
 func (e *Err) WithField(key string, val any) *Err {
 	return e.WithFields(fields.F(key, val))
 }
 
-// Fields returns fields of the error.
+// Fields returns the metadata fields attached to the Err.
 func (e *Err) Fields() fields.List {
 	return e.fields
 }
 
-// Reason returns reason string of the error without fields and wrapped errors.
+// Reason returns the reason string of the Err, without fields or wrapped errors.
+// If the Err is nil, returns "(*e.Err)(nil)". If empty, returns "(*e.Err)(empty)".
 func (e *Err) Reason() string {
 	if e == nil {
 		return "(*e.Err)(nil)"
@@ -133,8 +132,9 @@ func (e *Err) Reason() string {
 	return e.errs[0].Error()
 }
 
-// Unwrap implemented only for purposes of compatibility with [errors.Is] and
-// [errors.As] methods.
+// Unwrap returns the underlying errors for compatibility with errors.Is and errors.As.
+//
+// Deprecated: This method is for internal use only. Prefer using the errors package directly.
 func (e *Err) Unwrap() []error {
 	return e.errs
 }

e/log.go

@@ -4,24 +4,20 @@ import (
 	"dev.gaijin.team/go/golib/fields"
 )
 
+// ErrorLogger defines a function that logs an error message, an error, and optional fields.
 type ErrorLogger func(msg string, err error, fs ...fields.Field)
 
-// Log logs the provided error using the given logger.
+// Log logs the provided error using the given ErrorLogger function.
 //
-// If the error is nil, the function does nothing.
-//
-// If the error is of type [Err], its reason is used as the error message, the
-// wrapped error is passed as the actual error, and the error's fields are passed
-// as log fields.
-//
-// Otherwise, err.Error() is used as the error message, and nil is passed as the
-// actual error.
+// If err is nil, Log does nothing. If err is of type Err, its reason is used as the log message,
+// the wrapped error is passed as the error, and its fields are passed as log fields.
+// For other error types, err.Error() is used as the message and nil is passed as the error.
 func Log(err error, f ErrorLogger) {
 	if err == nil {
 		return
 	}
 
-	// we're not interested in wrapped error, therefore we're only typecasting it.
+	// We're not interested in wrapped error, therefore we're only typecasting it.
 	if e, ok := err.(*Err); ok { //nolint:errorlint
 		var wrapped error
 		if len(e.errs) > 1 {