Merge pull request #1459 from wprzytula/document-features

Document features in `Cargo.toml`

Author: wprzytula

README.md

@@ -64,6 +64,11 @@ The driver supports the following:
 
 For planned future improvements, see our [Milestones].
 
+### Feature flags
+The driver has several optional features that can be enabled or disabled in `Cargo.toml`.
+Refer to [scylla/Cargo.toml](https://docs.rs/crate/scylla/latest/source/Cargo.toml.orig)
+for the list of available features and their descriptions.
+
 ## Getting Help
 
 We invite you to discuss any issues and ask questions on the [ScyllaDB Forum] and the `#rust-driver` channel on [ScyllaDB Slack].

scylla-cql/Cargo.toml

@@ -6,13 +6,36 @@ rust-version = "1.85"
 description = "CQL data types and primitives, for interacting with ScyllaDB."
 repository = "https://github.com/scylladb/scylla-rust-driver"
 readme = "../README.md"
-keywords = ["database", "scylla", "cql", "cassandra"]
+keywords = ["database", "scylla", "scylladb", "cql", "cassandra"]
 categories = ["database"]
 license = "MIT OR Apache-2.0"
 
 [package.metadata."docs.rs"]
 all-features = true
 
+[features]
+# Enables support for CQL ser/de of Secrecy type from secrecy 0.8 crate.
+secrecy-08 = ["dep:secrecy-08"]
+# Enables support for CQL ser/de of time/date types from time 0.3 crate.
+time-03 = ["dep:time-03"]
+# Enables support for CQL ser/de of time/date types from chrono 0.4 crate.
+chrono-04 = []
+# Enables support for CQL ser/de of arbitrary length integer types from num-bigint 0.3 crate.
+num-bigint-03 = ["dep:num-bigint-03"]
+# Enables support for CQL ser/de of arbitrary length integer types from num-bigint 0.4 crate.
+num-bigint-04 = ["dep:num-bigint-04"]
+# Enables support for CQL ser/de of arbitrary precision decimal types from bigdecimal 0.4 crate.
+bigdecimal-04 = ["dep:bigdecimal-04"]
+# Enables support for CQL ser/de of all supported external types.
+full-serialization = [
+    "chrono-04",
+    "time-03",
+    "secrecy-08",
+    "num-bigint-03",
+    "num-bigint-04",
+    "bigdecimal-04",
+]
+
 [dependencies]
 ###########################
 # Main, public dependencies
@@ -74,22 +97,6 @@ uuid = { version = "1.0", features = ["v4"] }
 name = "benchmark"
 harness = false
 
-[features]
-secrecy-08 = ["dep:secrecy-08"]
-time-03 = ["dep:time-03"]
-chrono-04 = []
-num-bigint-03 = ["dep:num-bigint-03"]
-num-bigint-04 = ["dep:num-bigint-04"]
-bigdecimal-04 = ["dep:bigdecimal-04"]
-full-serialization = [
-    "chrono-04",
-    "time-03",
-    "secrecy-08",
-    "num-bigint-03",
-    "num-bigint-04",
-    "bigdecimal-04",
-]
-
 [lints.rust]
 unnameable_types = "warn"
 unreachable_pub = "warn"

scylla-proxy/Cargo.toml

@@ -3,10 +3,10 @@ name = "scylla-proxy"
 version = "0.0.4"
 edition = "2024"
 rust-version = "1.85"
-description = "Proxy layer between Scylla driver and cluster that enables testing Scylla drivers' behaviour in unfavourable conditions"
+description = "Proxy layer between ScyllaDB driver and cluster that enables testing ScyllaDB drivers' behaviour in unfavourable conditions"
 repository = "https://github.com/scylladb/scylla-rust-driver"
 readme = "../README.md"
-keywords = ["database", "scylla", "cql", "cassandra"]
+keywords = ["database", "scylla", "scylladb", "cql", "cassandra"]
 categories = ["database"]
 license = "MIT OR Apache-2.0"
 

scylla/Cargo.toml

@@ -3,10 +3,10 @@ name = "scylla"
 version = "1.3.1"
 edition = "2024"
 rust-version = "1.85"
-description = "Async CQL driver for Rust, optimized for Scylla, fully compatible with Apache Cassandra™"
+description = "Async CQL driver for Rust, optimized for ScyllaDB, fully compatible with Apache Cassandra™"
 repository = "https://github.com/scylladb/scylla-rust-driver"
 readme = "../README.md"
-keywords = ["database", "scylla", "cql", "cassandra"]
+keywords = ["database", "scylla", "scylladb", "cql", "cassandra"]
 categories = ["database"]
 license = "MIT OR Apache-2.0"
 
@@ -16,21 +16,31 @@ rustdoc-args = ["--cfg", "docsrs"]
 
 [features]
 default = []
+# Enables TLS support via OpenSSL 0.10.
 openssl-010 = ["dep:tokio-openssl", "dep:openssl"]
+# Enables TLS support via rustls 0.23.
 rustls-023 = ["dep:tokio-rustls", "dep:rustls"]
+# Enables features required to work with Scylla Serverless Cloud.
 unstable-cloud = [
     "scylla-cql/serde",
     "dep:serde_yaml",
     "dep:serde",
     "dep:url",
     "dep:base64",
 ]
+# Enables support for CQL ser/de of Secrecy type from secrecy 0.8 crate.
 secrecy-08 = ["scylla-cql/secrecy-08"]
+# Enables support for CQL ser/de of time/date types from chrono 0.4 crate.
 chrono-04 = ["scylla-cql/chrono-04"]
+# Enables support for CQL ser/de of time/date types from time 0.3 crate.
 time-03 = ["scylla-cql/time-03"]
+# Enables support for CQL ser/de of arbitrary length integer types from num-bigint 0.3 crate.
 num-bigint-03 = ["scylla-cql/num-bigint-03"]
+# Enables support for CQL ser/de of arbitrary length integer types from num-bigint 0.4 crate.
 num-bigint-04 = ["scylla-cql/num-bigint-04"]
+# Enables support for CQL ser/de of arbitrary precision decimal types from bigdecimal 0.4 crate.
 bigdecimal-04 = ["scylla-cql/bigdecimal-04"]
+# Enables support for CQL ser/de of all supported external types.
 full-serialization = [
     "chrono-04",
     "time-03",
@@ -39,7 +49,9 @@ full-serialization = [
     "num-bigint-04",
     "bigdecimal-04",
 ]
+# Enables collection of internal driver metrics.
 metrics = ["dep:histogram"]
+# Opts-in to various unstable testing features.
 unstable-testing = []
 
 [dependencies]
@@ -56,7 +68,7 @@ tokio = { version = "1.40", features = [
     "macros",
 ] }
 tracing = "0.1.36"
-# Appears in various places of our public API
+# Appears in various places of our public API.
 bytes = "1.0.1"
 # Used for representing tracing ids and host ids.
 uuid = { version = "1.0", features = ["v4"] }

scylla/src/lib.rs

@@ -1,19 +1,19 @@
-//! Async Rust driver for the [Scylla](https://scylladb.com) database written in Rust.
-//! Although optimized for Scylla, the driver is also compatible with [Apache Cassandra®](https://cassandra.apache.org/).
+//! Async Rust driver for the [ScyllaDB](https://scylladb.com) database written in Rust.
+//! Although optimized for ScyllaDB, the driver is also compatible with [Apache Cassandra®](https://cassandra.apache.org/).
 //!
 //! # Documentation book
 //! The best source to learn about this driver is the [documentation book](https://rust-driver.docs.scylladb.com/).\
-//! This page contains mainly API documentation
+//! This page contains mainly API documentation.
 //!
 //! # Other documentation
 //! * [Documentation book](https://rust-driver.docs.scylladb.com/)
 //! * [Examples](https://github.com/scylladb/scylla-rust-driver/tree/main/examples)
-//! * [Scylla documentation](https://docs.scylladb.com)
+//! * [ScyllaDB documentation](https://docs.scylladb.com)
 //! * [Cassandra® documentation](https://cassandra.apache.org/doc/latest/)
 //!
 //! # Driver overview
 //! ### Connecting
-//! All driver activity revolves around the [Session](crate::client::session::Session)\
+//! All driver activity revolves around the [Session](crate::client::session::Session).\
 //! `Session` is created by specifying a few known nodes and connecting to them:
 //!
 //! ```rust,no_run
@@ -44,7 +44,7 @@
 //! * [Prepared paged](crate::client::session::Session::execute_iter)
 //! * [Batch](crate::client::session::Session::batch)
 //!
-//! To specify options for a single query create the query object and configure it:
+//! To specify options for a single query, create the corresponding object and configure it:
 //! * For simple: [`Statement`](crate::statement::unprepared::Statement)
 //! * For prepared: [`PreparedStatement`](crate::statement::prepared::PreparedStatement)
 //! * For batch: [`Batch`](crate::statement::batch::Batch)
@@ -74,7 +74,7 @@
 //! # use std::error::Error;
 //! # async fn check_only_compiles(session: &Session) -> Result<(), Box<dyn Error>> {
 //!
-//! // Read rows containing an int and text
+//! // Read rows containing an int and text.
 //! // Keep in mind that all results come in one response (no paging is done!),
 //! // so the memory footprint and latency may be huge!
 //! // To prevent that, use `Session::query_iter` or `Session::query_single_page`.
@@ -90,7 +90,12 @@
 //! # Ok(())
 //! # }
 //! ```
-//! See the [book](https://rust-driver.docs.scylladb.com/stable/statements/result.html) for more receiving methods
+//! See the [book](https://rust-driver.docs.scylladb.com/stable/statements/result.html) for more receiving methods.
+//!
+//! # Feature flags
+//! The driver has several optional features that can be enabled or disabled in `Cargo.toml`.
+//! Refer to [scylla/Cargo.toml](https://docs.rs/crate/scylla/latest/source/Cargo.toml.orig)
+//! for the list of available features and their descriptions.
 
 #![cfg_attr(docsrs, feature(doc_auto_cfg))]