doc: comment the code

Signed-off-by: Jeremie Drouet <jeremie.drouet@gmail.com>

Author: jdrouet

src/lib.rs

@@ -16,6 +16,8 @@ pub mod postgres;
 #[cfg(feature = "sqlite")]
 pub mod sqlite;
 
+/// Attributes describing the database connection and context.
+/// Used for span enrichment and attribute propagation.
 #[derive(Debug, Default)]
 struct Attributes {
     name: Option<String>,
@@ -24,13 +26,18 @@ struct Attributes {
     database: Option<String>,
 }
 
+/// Builder for constructing a [`Pool`] with custom attributes.
+///
+/// Allows setting database name, host, port, and other identifying information
+/// for tracing purposes.
 #[derive(Debug)]
 pub struct PoolBuilder<DB: sqlx::Database> {
     pool: sqlx::Pool<DB>,
     attributes: Attributes,
 }
 
 impl<DB: sqlx::Database> PoolBuilder<DB> {
+    /// Create a new builder from an existing SQLx pool.
     pub fn new(pool: sqlx::Pool<DB>) -> Self {
         let url = pool.connect_options().to_url_lossy();
         let attributes = Attributes {
@@ -44,26 +51,31 @@ impl<DB: sqlx::Database> PoolBuilder<DB> {
         Self { pool, attributes }
     }
 
+    /// Set a custom name for the pool (for peer.service attribute).
     pub fn with_name(mut self, name: impl Into<String>) -> Self {
         self.attributes.name = Some(name.into());
         self
     }
 
+    /// Set the database name attribute.
     pub fn with_database(mut self, database: impl Into<String>) -> Self {
         self.attributes.database = Some(database.into());
         self
     }
 
+    /// Set the host attribute.
     pub fn with_host(mut self, host: impl Into<String>) -> Self {
         self.attributes.host = Some(host.into());
         self
     }
 
+    /// Set the port attribute.
     pub fn with_port(mut self, port: u16) -> Self {
         self.attributes.port = Some(port);
         self
     }
 
+    /// Build the [`Pool`] with the configured attributes.
     pub fn build(self) -> Pool<DB> {
         Pool {
             inner: self.pool,
@@ -72,7 +84,9 @@ impl<DB: sqlx::Database> PoolBuilder<DB> {
     }
 }
 
-/// An asynchronous pool of SQLx database connections.
+/// An asynchronous pool of SQLx database connections with tracing instrumentation.
+///
+/// Wraps a SQLx [`Pool`] and propagates tracing attributes to all acquired connections.
 #[derive(Clone, Debug)]
 pub struct Pool<DB>
 where
@@ -86,6 +100,7 @@ impl<DB> From<sqlx::Pool<DB>> for Pool<DB>
 where
     DB: sqlx::Database,
 {
+    /// Convert a SQLx [`Pool`] into a tracing-instrumented [`Pool`].
     fn from(inner: sqlx::Pool<DB>) -> Self {
         PoolBuilder::new(inner).build()
     }
@@ -96,14 +111,16 @@ where
     DB: sqlx::Database,
 {
     /// Retrieves a connection and immediately begins a new transaction.
+    ///
+    /// The returned [`Transaction`] is instrumented for tracing.
     pub async fn begin<'c>(&'c self) -> Result<Transaction<'c, DB>, sqlx::Error> {
         self.inner.begin().await.map(|inner| Transaction {
             inner,
             attributes: self.attributes.clone(),
         })
     }
 
-    /// Retrieves a connection and immediately begins a new transaction.
+    /// Acquires a pooled connection, instrumented for tracing.
     pub async fn acquire(&self) -> Result<PoolConnection<DB>, sqlx::Error> {
         self.inner.acquire().await.map(|inner| PoolConnection {
             attributes: self.attributes.clone(),
@@ -112,6 +129,9 @@ where
     }
 }
 
+/// Wrapper for a mutable SQLx connection reference with tracing attributes.
+///
+/// Used internally for transaction and pool connection executors.
 pub struct Connection<'c, DB>
 where
     DB: sqlx::Database,
@@ -126,6 +146,9 @@ impl<'c, DB: sqlx::Database> std::fmt::Debug for Connection<'c, DB> {
     }
 }
 
+/// A pooled SQLx connection instrumented for tracing.
+///
+/// Implements [`sqlx::Executor`] and propagates tracing attributes.
 #[derive(Debug)]
 pub struct PoolConnection<DB>
 where
@@ -135,7 +158,9 @@ where
     attributes: Arc<Attributes>,
 }
 
-/// An in-progress database transaction or savepoint.
+/// An in-progress database transaction or savepoint, instrumented for tracing.
+///
+/// Wraps a SQLx [`Transaction`] and propagates tracing attributes.
 #[derive(Debug)]
 pub struct Transaction<'c, DB>
 where

src/span.rs

@@ -1,34 +1,57 @@
+/// Macro to create a tracing span for a SQLx operation with OpenTelemetry-compatible fields.
+///
+/// - `$name`: The operation name (e.g., "sqlx.execute").
+/// - `$statement`: The SQL statement being executed.
+/// - `$attributes`: Connection or pool attributes for peer and db context.
+///
+/// This macro is used internally by the crate to instrument all major SQLx operations.
 #[macro_export]
 macro_rules! instrument {
     ($name:expr, $statement:expr, $attributes:expr) => {
         tracing::info_span!(
             $name,
+            // Database name (if available)
             "db.name" = $attributes.database,
+            // Operation type (filled by SQLx or left empty)
             "db.operation" = ::tracing::field::Empty,
+            // The SQL query text
             "db.query.text" = $statement,
+            // Number of affected rows (to be filled after execution)
             "db.response.affected_rows" = ::tracing::field::Empty,
+            // Number of returned rows (to be filled after execution)
             "db.response.returned_rows" = ::tracing::field::Empty,
+            // Status code of the response (to be filled after execution)
             "db.response.status_code" = ::tracing::field::Empty,
+            // Table name (optional, left empty)
             "db.sql.table" = ::tracing::field::Empty,
+            // Database system (e.g., "postgresql", "sqlite")
             "db.system.name" = DB::SYSTEM,
+            // Error type, message, and stacktrace (to be filled on error)
             "error.type" = ::tracing::field::Empty,
             "error.message" = ::tracing::field::Empty,
             "error.stacktrace" = ::tracing::field::Empty,
+            // Peer (server) host and port
             "net.peer.name" = $attributes.host,
             "net.peer.port" = $attributes.port,
+            // OpenTelemetry semantic fields
             "otel.kind" = "client",
             "otel.status_code" = ::tracing::field::Empty,
             "otel.status_description" = ::tracing::field::Empty,
+            // Peer service name (if set)
             "peer.service" = $attributes.name,
         )
     };
 }
 
+/// Records that a single row was returned in the current tracing span.
+/// Used for fetch_one operations.
 pub fn record_one<T>(_value: &T) {
     let span = tracing::Span::current();
     span.record("db.response.returned_rows", 1);
 }
 
+/// Records whether an optional row was returned in the current tracing span.
+/// Used for fetch_optional operations.
 pub fn record_optional<T>(value: &Option<T>) {
     let span = tracing::Span::current();
     span.record(
@@ -37,10 +60,14 @@ pub fn record_optional<T>(value: &Option<T>) {
     );
 }
 
+/// Records error details in the current tracing span for a SQLx error.
+/// Sets OpenTelemetry status and error fields for observability backends.
 pub fn record_error(err: &sqlx::Error) {
     let span = tracing::Span::current();
+    // Mark the span as an error for OpenTelemetry
     span.record("otel.status_code", "error");
     span.record("otel.status_description", err.to_string());
+    // Classify error type as client or server
     match err {
         sqlx::Error::ColumnIndexOutOfBounds { .. }
         | sqlx::Error::ColumnDecode { .. }
@@ -55,6 +82,7 @@ pub fn record_error(err: &sqlx::Error) {
             span.record("error.type", "server");
         }
     }
+    // Attach error message and stacktrace for debugging
     span.record("error.message", err.to_string());
     span.record("error.stacktrace", format!("{err:?}"));
 }

src/transaction.rs

@@ -6,6 +6,9 @@ where
     DB: crate::prelude::Database + sqlx::Database,
     for<'a> &'a mut DB::Connection: sqlx::Executor<'a, Database = DB>,
 {
+    /// Returns a tracing-instrumented executor for this transaction.
+    ///
+    /// This allows running queries with full span context and attributes.
     pub fn executor(&mut self) -> crate::Connection<'_, DB> {
         crate::Connection {
             inner: &mut *self.inner,
@@ -14,6 +17,10 @@ where
     }
 }
 
+/// Implements `sqlx::Executor` for a mutable reference to a tracing-instrumented transaction.
+///
+/// Each method creates a tracing span for the SQL operation, attaches relevant attributes,
+/// and records errors or row counts as appropriate for observability.
 impl<'c, DB> sqlx::Executor<'c> for &'c mut crate::Transaction<'c, DB>
 where
     DB: crate::prelude::Database + sqlx::Database,