Document Session interface and Pool convenience methods

lib/postgres.dart

@@ -125,6 +125,18 @@ class Sql {
   factory Sql.named(String sql, {String substitution}) = SqlImpl.named;
 }
 
+/// A capability for preparing and executing SQL statements.
+///
+/// This is **not** necessarily a 1:1 mapping to a PostgreSQL physical database
+/// connection or session.
+///
+/// An implementation may represent:
+///
+/// - a dedicated database connection.
+/// - a session executed on a connection borrowed from a pool.
+/// - or another abstraction capable of executing queries.
+///
+/// A session may also operate in a transactional context ([TxSession]).
 abstract class Session {
   /// Whether this connection is currently open.
   ///

lib/src/pool/pool_api.dart

@@ -57,6 +57,10 @@ class PoolSettings extends ConnectionSettings {
 ///   specified data range.
 /// - a primary/replica status, whic may be specified for cases where stale or
 ///   read-only data is acceptable
+///
+/// This interface implements [Session] and [SessionExecutor] as a convenience
+/// API that internally acquires a pooled connection via [withConnection] for
+/// each operation.
 abstract class Pool<L> implements Session, SessionExecutor {
   factory Pool.withSelector(
     EndpointSelector<L> selector, {
@@ -125,8 +129,9 @@ abstract class Pool<L> implements Session, SessionExecutor {
   // TODO: decide whether PgSession.execute and prepare methods should also take locality parameter
 }
 
-typedef EndpointSelector<L> =
-    FutureOr<EndpointSelection> Function(EndpointSelectorContext<L> context);
+typedef EndpointSelector<L> = FutureOr<EndpointSelection> Function(
+  EndpointSelectorContext<L> context,
+);
 
 final class EndpointSelectorContext<L> {
   final L? locality;