[#68] improve Transactor methods description

stdlib/transactor.go

@@ -19,11 +19,12 @@ type Executor interface {
 	PrepareContext(ctx context.Context, query string) (*sql.Stmt, error)
 }
 
-// dbWrapper is sql.DB wrapper, implements oniontx.TxBeginner.
+// dbWrapper wraps sql.DB, implements oniontx.TxBeginner.
 type dbWrapper struct {
 	*sql.DB
 }
 
+// BeginTx starts a transaction.
 func (db *dbWrapper) BeginTx(ctx context.Context, opts ...oniontx.Option[*sql.TxOptions]) (*txWrapper, error) {
 	var txOptions sql.TxOptions
 	for _, opt := range opts {
@@ -33,15 +34,17 @@ func (db *dbWrapper) BeginTx(ctx context.Context, opts ...oniontx.Option[*sql.Tx
 	return &txWrapper{Tx: tx}, err
 }
 
-// txWrapper is sql.Tx wrapper, implements oniontx.Tx.
+// txWrapper wraps sql.Tx, implements oniontx.Tx.
 type txWrapper struct {
 	*sql.Tx
 }
 
+// Rollback aborts the transaction.
 func (t *txWrapper) Rollback(_ context.Context) error {
 	return t.Tx.Rollback()
 }
 
+// Commit commits the transaction.
 func (t *txWrapper) Commit(_ context.Context) error {
 	return t.Tx.Commit()
 }

transactor.go

@@ -16,20 +16,24 @@ var (
 )
 
 type (
+	// TxBeginner is responsible for creating new Tx.
 	TxBeginner[T Tx, O any] interface {
 		comparable
 		BeginTx(ctx context.Context, opts ...Option[O]) (T, error)
 	}
 
+	// Tx represent transaction contract.
 	Tx interface {
 		Rollback(ctx context.Context) error
 		Commit(ctx context.Context) error
 	}
 
+	// Option applying to new Tx.
 	Option[TxOpt any] interface {
 		Apply(in TxOpt)
 	}
 
+	// СtxOperator is responsible for interaction with context.Context to store or extract Tx.
 	СtxOperator[T Tx] interface {
 		Inject(ctx context.Context, tx T) context.Context
 		Extract(ctx context.Context) (T, bool)
@@ -54,12 +58,39 @@ func NewTransactor[B TxBeginner[T, O], T Tx, O any](
 
 // WithinTx execute all queries with Tx.
 // The function create new Tx or reuse Tx obtained from context.Context.
+//
+// The behavior described on WithinTxWithOpts function's docs.
 func (t *Transactor[B, T, O]) WithinTx(ctx context.Context, fn func(ctx context.Context) error) (err error) {
 	return t.WithinTxWithOpts(ctx, fn)
 }
 
 // WithinTxWithOpts execute all queries with Tx and transaction Options.
 // The function create new Tx or reuse Tx obtained from context.Context.
+/*
+When WithinTxWithOpts call recursively, the highest level function responsible for creating transaction and applying commit or rollback of a transaction.
+
+		tr := NewTransactor[...](...)
+		err := tr.WithinTx(ctx, func(ctx context.Context) error { // create transaction (with options) and commit/rollback execute on this level
+			// some logic
+
+			err := tr.WithinTx(ctx, func(ctx context.Context) error {
+				// some logic
+			})
+
+			err = tr.WithinTx(ctx, func(ctx context.Context) error {
+				// some logic
+			})
+			// some logic
+		})
+
+Note:
+
++ a processed error returns to the highest level function for commit or rollback.
+
++ panics are transformed to errors with the same messages.
+
++ higher level panics override lower level panics.
+*/
 func (t *Transactor[B, T, O]) WithinTxWithOpts(ctx context.Context, fn func(ctx context.Context) error, opts ...Option[O]) (err error) {
 	var (
 		nilBeginner B