Add some docs

rust/Cargo.toml

@@ -23,6 +23,7 @@ resolver = "2"
 version = "0.16.0"
 description = "Rust implementation of Arrow Database Connectivity (ADBC)"
 edition = "2021"
+rust-version = "1.80.1"
 authors = ["Apache Arrow <[email protected]>"]
 license = "Apache-2.0"
 documentation = "https://docs.rs/adbc_core/"

rust/driver/snowflake/Cargo.toml

@@ -22,6 +22,13 @@ version.workspace = true
 edition.workspace = true
 authors.workspace = true
 license.workspace = true
+homepage.workspace = true
+repository.workspace = true
+rust-version.workspace = true
+keywords.workspace = true
+categories.workspace = true
+documentation = "http://docs.rs/adbc_snowflake/"
+readme = "README.md"
 
 [features]
 default = ["bundled", "env", "dotenv"]

rust/driver/snowflake/README.md

@@ -17,4 +17,89 @@
   under the License.
 -->
 
+![logo](https://raw.githubusercontent.com/apache/arrow/refs/heads/main/docs/source/_static/favicon.ico)
+
+[![crates.io](https://img.shields.io/crates/v/adbc_snowflake.svg)](https://crates.io/crates/adbc_snowflake)
+[![docs.rs](https://docs.rs/adbc_snowflake/badge.svg)](https://docs.rs/c)
+
 # Snowflake driver for Arrow Database Connectivity (ADBC)
+
+A [Snowflake](https://www.snowflake.com) [ADBC](https://arrow.apache.org/adbc/)
+driver, based on the
+[ADBC Snowflake Go driver](https://github.com/apache/arrow-adbc/tree/main/go/adbc/driver/snowflake).
+
+## Example
+
+```rust
+# #![doc(test(attr(test_with::env(ADBC_SNOWFLAKE_TESTS))))]
+use adbc_core::{Connection, Statement};
+use adbc_snowflake::{connection, database, Driver};
+use arrow_array::{cast::AsArray, types::Decimal128Type};
+
+# #[cfg(feature = "env")]
+# fn main() -> Result<(), Box<dyn std::error::Error>> {
+
+// Load the driver
+let mut driver = Driver::try_load()?;
+
+// Construct a database using environment variables
+let mut database = database::Builder::from_env().build(&mut driver)?;
+
+// Create a connection to the database
+let mut connection = connection::Builder::from_env().build(&mut database)?;
+
+// Construct a statement to execute a query
+let mut statement = connection.new_statement()?;
+
+// Execute a query
+statement.set_sql_query("SELECT 21 + 21")?;
+let mut reader = statement.execute()?;
+
+// Check the result
+let batch = reader.next().expect("a record batch")?;
+assert_eq!(
+    batch.column(0).as_primitive::<Decimal128Type>().value(0),
+    42
+);
+
+# Ok(()) }
+# #[cfg(not(feature = "env"))]
+# fn main() {}
+```
+
+## Crate features
+
+### Linking Go driver
+
+This crate is a wrapper around the Go driver.
+
+There are different methods to load the Go driver:
+
+#### `bundled` (default)
+
+Builds the driver from source and links it statically. This requires a Go
+compiler to be available at build time. This is the default behavior.
+
+#### `linked`
+
+Link the driver at build time. This requires the driver library to be available
+both at build- and runtime. Set `ADBC_SNOWFLAKE_GO_LIB_DIR` during the build to
+add search paths for the linker.
+
+#### Runtime only
+
+It's also possible to build this crate without the driver and only link at
+runtime. This requires disabling the `bundled` and `linked` features. Linking
+at runtime is also available when the other features are enabled.
+
+### Configuration
+
+The crate provides builders that can be initialized from environment variables.
+
+#### `env` (default)
+
+Adds `from_env` methods to initialize builders from environment variables.
+
+#### `dotenv`: `env` (default)
+
+Loads environment variables from `.env` files in `from_env` methods.

rust/driver/snowflake/src/builder.rs

@@ -15,7 +15,8 @@
 // specific language governing permissions and limitations
 // under the License.
 
-//! Builder utility.
+//! Builder utilities
+//!
 //!
 
 use std::iter::{Chain, Flatten};

rust/driver/snowflake/src/connection.rs

@@ -15,6 +15,10 @@
 // specific language governing permissions and limitations
 // under the License.
 
+//! Snowflake ADBC Connection
+//!
+//!
+
 use std::collections::HashSet;
 
 use adbc_core::{

rust/driver/snowflake/src/connection/builder.rs

@@ -15,7 +15,7 @@
 // specific language governing permissions and limitations
 // under the License.
 
-//! A builder for a [`Connection`].
+//! A builder for a [`Connection`]
 //!
 //!
 

rust/driver/snowflake/src/database.rs

@@ -15,6 +15,10 @@
 // specific language governing permissions and limitations
 // under the License.
 
+//! Snowflake ADBC Database
+//!
+//!
+
 use std::{collections::HashSet, ffi::c_int, sync::Arc};
 
 use adbc_core::{

rust/driver/snowflake/src/database/builder.rs

@@ -15,7 +15,7 @@
 // specific language governing permissions and limitations
 // under the License.
 
-//! A builder for a [`Database`].
+//! A builder for a [`Database`]
 //!
 //!
 

rust/driver/snowflake/src/driver.rs

@@ -15,6 +15,10 @@
 // specific language governing permissions and limitations
 // under the License.
 
+//! Snowflake ADBC Driver
+//!
+//!
+
 #[cfg(any(feature = "bundled", feature = "linked"))]
 use std::ffi::{c_int, c_void};
 use std::{fmt, sync::LazyLock};
@@ -74,9 +78,36 @@ impl Driver {
     /// or to load the configuration from environment variables use
     /// [`Builder::from_env`].
     ///
+    /// If the crate was built without the `bundled` and `linked` features this
+    /// will attempt to dynamically load the driver.
+    ///
     /// # Error
     ///
     /// Returns an error when the driver fails to load.
+    ///
+    /// # Example
+    ///
+    /// ## Using the default ADBC version
+    ///
+    /// ```rust
+    /// # use adbc_core::error::Result;
+    /// # use adbc_snowflake::Driver;
+    /// # fn main() -> Result<()> {
+    /// let mut driver = Driver::try_load()?;
+    /// # Ok(()) }
+    /// ```
+    ///
+    /// ## Using a different ADBC version
+    ///
+    /// ```rust
+    /// # use adbc_core::{error::Result, options::AdbcVersion};
+    /// # use adbc_snowflake::{driver::Builder, Driver};
+    /// # fn main() -> Result<()> {
+    /// let mut driver = Builder::default()
+    ///    .with_adbc_version(AdbcVersion::V100)
+    ///    .try_load()?;
+    /// # Ok(()) }
+    /// ```
     pub fn try_load() -> Result<Self> {
         Self::try_new(Default::default())
     }
@@ -104,6 +135,20 @@ impl Driver {
     ///
     /// This attempts to load the `adbc_driver_snowflake` library using the
     /// default `AdbcVersion`.
+    ///
+    /// # Error
+    ///
+    /// Returns an error when the driver fails to load.
+    ///
+    /// # Example
+    ///
+    /// ```rust,ignore
+    /// # use adbc_core::error::Result;
+    /// # use adbc_snowflake::Driver;
+    /// # fn main() -> Result<()> {
+    /// let mut driver = Driver::try_load_dynamic()?;
+    /// # Ok(()) }
+    /// ```
     pub fn try_load_dynamic() -> Result<Self> {
         Self::try_new_dynamic()
     }

rust/driver/snowflake/src/driver/builder.rs

@@ -15,7 +15,7 @@
 // specific language governing permissions and limitations
 // under the License.
 
-//! A builder for [`Driver`].
+//! A builder for [`Driver`]
 //!
 //!
 

rust/driver/snowflake/src/duration.rs

@@ -15,7 +15,8 @@
 // specific language governing permissions and limitations
 // under the License.
 
-//! A parser for [`Duration`] following <https://pkg.go.dev/time#ParseDuration>.
+//! A parser for [`Duration`] following <https://pkg.go.dev/time#ParseDuration>
+//!
 //!
 
 use std::{error::Error as StdError, num::IntErrorKind, sync::LazyLock, time::Duration};

rust/driver/snowflake/src/lib.rs

@@ -15,35 +15,12 @@
 // specific language governing permissions and limitations
 // under the License.
 
-//! Snowflake ADBC driver, based on the Go driver.
-//!
-//! # Features
-//!
-//! ## Linking
-//!
-//! ### `bundled` (default)
-//!
-//! Builds the Go Snowflake driver from source and links it statically. This
-//! requires a Go compiler to be installed.
-//!
-//! ### `linked`
-//!
-//! Link the Go Snowflake driver at build time. Set `ADBC_SNOWFLAKE_GO_LIB_DIR`
-//! to add a search paths for the linker.
-//!
-//! ## Configuration
-//!
-//! ### `env` (default)
-//!
-//! Adds `from_env` methods to initialize builders from environment variables.
-//!
-//! ### `dotenv`: `env` (default)
-//!
-//! Loads environment variables from `.env` files in `from_env` methods.
-//!
-//!
-
 #![cfg_attr(docsrs, feature(doc_auto_cfg, doc_cfg))]
+#![doc(
+    html_logo_url = "https://raw.githubusercontent.com/apache/arrow/refs/heads/main/docs/source/_static/favicon.ico",
+    html_favicon_url = "https://raw.githubusercontent.com/apache/arrow/refs/heads/main/docs/source/_static/favicon.ico"
+)]
+#![doc = include_str!(concat!(env!("CARGO_MANIFEST_DIR"), "/README.md"))]
 
 pub mod driver;
 pub use driver::Driver;
@@ -57,7 +34,7 @@ pub use connection::Connection;
 pub mod statement;
 pub use statement::Statement;
 
-pub mod builder;
+pub(crate) mod builder;
 
 #[cfg(feature = "env")]
 pub(crate) mod duration;

rust/driver/snowflake/src/statement.rs

@@ -15,6 +15,10 @@
 // specific language governing permissions and limitations
 // under the License.
 
+//! Snowflake ADBC Statement
+//!
+//!
+
 use adbc_core::{
     driver_manager::ManagedStatement,
     error::Result,