Merge pull request #1400 from wprzytula/scylla-more-docs

scylla: Write missing docstrings

Author: wprzytula

scylla-cql/benches/benchmark.rs

@@ -1,3 +1,5 @@
+#![allow(missing_docs)]
+
 use std::borrow::Cow;
 
 use criterion::{criterion_group, criterion_main, BenchmarkId, Criterion};

scylla/Cargo.toml

@@ -140,6 +140,7 @@ required-features = ["unstable-testing"]
 [lints.rust]
 unnameable_types = "warn"
 unreachable_pub = "warn"
+missing-docs = "warn"
 unexpected_cfgs = { level = "warn", check-cfg = [
     'cfg(scylla_cloud_tests)',
     'cfg(cassandra_tests)',

scylla/benches/benchmark.rs

@@ -1,3 +1,5 @@
+#![allow(missing_docs)]
+
 use criterion::{criterion_group, criterion_main, Criterion};
 
 use bytes::BytesMut;

scylla/src/authentication/mod.rs

@@ -1,3 +1,5 @@
+//! Traits and implementations for custom authentication against a server.
+
 use async_trait::async_trait;
 use bytes::{BufMut, BytesMut};
 
@@ -25,7 +27,7 @@ pub trait AuthenticatorSession: Send + Sync {
 /// Trait used to represent a factory of [`AuthenticatorSession`] instances.
 /// A new [`AuthenticatorSession`] instance will be created for each session.
 ///
-/// The custom authenticator can be set using SessionBuilder::authenticator_provider method.  
+/// The custom authenticator can be set using SessionBuilder::authenticator_provider method.
 ///
 /// Default: [`PlainTextAuthenticator`] is the default authenticator which requires username and
 /// password. It can be set by using SessionBuilder::user(\"user\", \"pass\") method.

scylla/src/client/caching_session.rs

@@ -1,3 +1,6 @@
+//! Provides a convenient wrapper over the [`Session`] that caches
+//! prepared statements automatically and reuses them when possible.
+
 use crate::errors::{ExecutionError, PagerExecutionError, PrepareError};
 use crate::response::query_result::QueryResult;
 use crate::response::{PagingState, PagingStateResponse};
@@ -63,6 +66,7 @@ impl<S> CachingSession<S>
 where
     S: Default + BuildHasher + Clone,
 {
+    /// Builds a [`CachingSession`] from a [`Session`] and a cache size.
     pub fn from(session: Session, cache_size: usize) -> Self {
         Self {
             session: Arc::new(session),
@@ -246,10 +250,12 @@ where
         }
     }
 
+    /// Retrieves the maximum capacity of the prepared statements cache.
     pub fn get_max_capacity(&self) -> usize {
         self.max_capacity
     }
 
+    /// Retrieves the underlying [Session] instance.
     pub fn get_session(&self) -> &Session {
         &self.session
     }
@@ -297,11 +303,12 @@ where
 impl CachingSessionBuilder<RandomState> {
     /// Wraps a [Session] and creates a new [CachingSessionBuilder] instance,
     /// which can be used to create a new [CachingSession].
-    ///
     pub fn new(session: Session) -> Self {
         Self::new_shared(Arc::new(session))
     }
 
+    /// Wraps an Arc<[Session]> and creates a new [CachingSessionBuilder] instance,
+    /// which can be used to create a new [CachingSession].
     pub fn new_shared(session: Arc<Session>) -> Self {
         Self {
             session,

scylla/src/client/self_identity.rs

@@ -4,46 +4,52 @@ use std::borrow::Cow;
 /// to be sent in STARTUP message.
 #[derive(Debug, Clone, Default)]
 pub struct SelfIdentity<'id> {
-    // Custom driver identity can be set if a custom driver build is running,
-    // or an entirely different driver is operating on top of Rust driver
-    // (e.g. cpp-rust-driver).
+    /// Custom driver identity can be set if a custom driver build is running,
+    /// or an entirely different driver is operating on top of Rust driver
+    /// (e.g. cpp-rust-driver).
     custom_driver_name: Option<Cow<'id, str>>,
+    /// Custom driver identity can be set if a custom driver build is running,
+    /// or an entirely different driver is operating on top of Rust driver
+    /// (e.g. cpp-rust-driver).
     custom_driver_version: Option<Cow<'id, str>>,
 
     // ### Q: Where do APPLICATION_NAME, APPLICATION_VERSION and CLIENT_ID come from?
     // - there are no columns in system.clients dedicated to those attributes,
     // - APPLICATION_NAME / APPLICATION_VERSION are not present in Scylla's source code at all,
     // - only 2 results in Cassandra source is some example in docs:
-    //   https://github.com/apache/cassandra/blob/d3cbf9c1f72057d2a5da9df8ed567d20cd272931/doc/modules/cassandra/pages/managing/operating/virtualtables.adoc?plain=1#L218.
+    //   <https://github.com/apache/cassandra/blob/d3cbf9c1f72057d2a5da9df8ed567d20cd272931/doc/modules/cassandra/pages/managing/operating/virtualtables.adoc?plain=1#L218>.
     //   APPLICATION_NAME and APPLICATION_VERSION appears in client_options which
     //   is an arbitrary dict where client can send any keys.
     // - driver variables are mentioned in protocol v5
-    //   (https://github.com/apache/cassandra/blob/d3cbf9c1f72057d2a5da9df8ed567d20cd272931/doc/native_protocol_v5.spec#L480),
+    //   (<https://github.com/apache/cassandra/blob/d3cbf9c1f72057d2a5da9df8ed567d20cd272931/doc/native_protocol_v5.spec#L480>),
     //   application variables are not.
     //
     // ### A:
     // The following options are not exposed anywhere in ScyllaDB tables.
     // They come directly from CPP driver, and they are supported in Cassandra
     //
-    // See https://github.com/scylladb/cpp-driver/blob/fa0f27069a625057984d1fa58f434ea99b86c83f/include/cassandra.h#L2916.
+    // See <https://github.com/scylladb/cpp-driver/blob/fa0f27069a625057984d1fa58f434ea99b86c83f/include/cassandra.h#L2916>.
     // As we want to support as big subset of its API as possible in cpp-rust-driver, I decided to expose API for setting
     // those particular key-value pairs, similarly to what cpp-driver does, and not an API to set arbitrary key-value pairs.
     //
     // Allowing users to set arbitrary options could break the driver by overwriting options that bear special meaning,
     // e.g. the shard-aware port. Therefore, I'm against such liberal API. OTOH, we need to expose APPLICATION_NAME,
     // APPLICATION_VERSION and CLIENT_ID for cpp-rust-driver.
-
-    // Application identity can be set to distinguish different applications
-    // connected to the same cluster.
+    /// Application identity can be set to distinguish different applications
+    /// connected to the same cluster.
     application_name: Option<Cow<'id, str>>,
+    /// Application identity can be set to distinguish different applications
+    /// connected to the same cluster.
     application_version: Option<Cow<'id, str>>,
 
-    // A (unique) client ID can be set to distinguish different instances
-    // of the same application connected to the same cluster.
+    /// A (unique) client ID can be set to distinguish different instances
+    /// of the same application connected to the same cluster.
     client_id: Option<Cow<'id, str>>,
 }
 
 impl<'id> SelfIdentity<'id> {
+    /// Creates a new empty instance of [`SelfIdentity`], which has all fields
+    /// set to `None`.
     pub fn new() -> Self {
         Self::default()
     }

scylla/src/client/session.rs

@@ -124,11 +124,15 @@ impl std::fmt::Debug for Session {
     }
 }
 
+/// Represents a TLS context used to configure TLS connections to DB nodes.
+/// Abstracts over various TLS implementations, such as OpenSSL and Rustls.
 #[derive(Clone)] // Cheaply clonable - reference counted.
 #[non_exhaustive]
 pub enum TlsContext {
+    /// TLS context backed by OpenSSL 0.10.
     #[cfg(feature = "openssl-010")]
     OpenSsl010(openssl::ssl::SslContext),
+    /// TLS context backed by Rustls 0.23.
     #[cfg(feature = "rustls-023")]
     Rustls023(Arc<rustls::ClientConfig>),
 }
@@ -173,19 +177,41 @@ pub struct SessionConfig {
     /// Preferred compression algorithm to use on connections.
     /// If it's not supported by database server Session will fall back to no compression.
     pub compression: Option<Compression>,
+
+    /// Whether to set the nodelay TCP flag.
     pub tcp_nodelay: bool,
+
+    /// TCP keepalive interval, which means how often keepalive messages
+    /// are sent **on TCP layer** when a connection is idle.
+    /// If `None`, no TCP keepalive messages are sent.
     pub tcp_keepalive_interval: Option<Duration>,
 
+    /// Handle to the default execution profile, which is used
+    /// for all statements that do not specify an execution profile.
     pub default_execution_profile_handle: ExecutionProfileHandle,
 
+    /// Keyspace to be used on all connections.
+    /// Each connection will send `"USE <keyspace_name>"` before sending any requests.
+    /// This can be later changed with [`Session::use_keyspace`].
     pub used_keyspace: Option<String>,
+
+    /// Whether the keyspace name is case-sensitive.
+    /// This is used to determine how the keyspace name is sent to the server:
+    /// - if case-insensitive, it is sent as-is,
+    /// - if case-sensitive, it is enclosed in double quotes.
     pub keyspace_case_sensitive: bool,
 
-    /// Provide our Session with TLS
+    /// TLS context used configure TLS connections to DB nodes.
     pub tls_context: Option<TlsContext>,
 
+    /// Custom authenticator provider to create an authenticator instance
+    /// upon session creation.
     pub authenticator: Option<Arc<dyn AuthenticatorProvider>>,
 
+    /// Timeout for establishing connections to a node.
+    ///
+    /// If it's higher than underlying os's default connection timeout, it won't have
+    /// any effect.
     pub connect_timeout: Duration,
 
     /// Size of the per-node connection pool, i.e. how many connections the driver should keep to each node.

scylla/src/client/session_builder.rs

@@ -31,15 +31,23 @@ mod sealed {
     #[expect(unnameable_types)]
     pub trait Sealed {}
 }
+/// Kind of the session builder, used to distinguish between
+/// builders that create regular sessions and those that create custom
+/// sessions, such as cloud sessions.
+/// This is used to conditionally enable different sets of methods
+/// on the session builder based on its kind.
 pub trait SessionBuilderKind: sealed::Sealed + Clone {}
 
+/// Default session builder kind, used to create regular sessions.
 #[derive(Clone)]
 pub enum DefaultMode {}
 impl sealed::Sealed for DefaultMode {}
 impl SessionBuilderKind for DefaultMode {}
 
+/// Builder for regular sessions.
 pub type SessionBuilder = GenericSessionBuilder<DefaultMode>;
 
+/// Session builder kind for creating cloud sessions.
 #[cfg(feature = "unstable-cloud")]
 #[derive(Clone)]
 pub enum CloudMode {}
@@ -48,10 +56,17 @@ impl sealed::Sealed for CloudMode {}
 #[cfg(feature = "unstable-cloud")]
 impl SessionBuilderKind for CloudMode {}
 
+/// Builder for sessions that connect to Scylla Cloud.
 #[cfg(feature = "unstable-cloud")]
 pub type CloudSessionBuilder = GenericSessionBuilder<CloudMode>;
 
-/// SessionBuilder is used to create new Session instances
+/// Used to conveniently configure new Session instances.
+///
+/// Most likely you will want to use [`SessionBuilder`]
+/// (for building regular session). If you want to build a session
+/// that connects to Scylla Cloud, you will want to use
+/// `CloudSessionBuilder`.
+///
 /// # Example
 ///
 /// ```
@@ -69,6 +84,7 @@ pub type CloudSessionBuilder = GenericSessionBuilder<CloudMode>;
 /// ```
 #[derive(Clone)]
 pub struct GenericSessionBuilder<Kind: SessionBuilderKind> {
+    /// Configuration for the session being built.
     pub config: SessionConfig,
     kind: PhantomData<Kind>,
 }

scylla/src/cloud/config.rs

@@ -14,21 +14,27 @@ use crate::errors::TranslationError;
 use crate::network::tls::{TlsConfig, TlsError};
 use crate::policies::address_translator::{AddressTranslator, UntranslatedPeer};
 
+/// Error that can occur while parsing the cloud config yaml file.
 #[non_exhaustive]
 #[derive(Debug, Error)]
 pub enum CloudConfigError {
+    /// Error while opening cloud config yaml.
     #[error("Error while opening cloud config yaml: {0}")]
     YamlOpen(#[from] io::Error),
 
+    /// Error while parsing cloud config yaml.
     #[error("Error while parsing cloud config yaml: {0}")]
     YamlParse(#[from] serde_yaml::Error),
 
+    /// Error while decoding base64 key/cert.
     #[error("Error while decoding base64 key/cert: {0}")]
     Base64(#[from] base64::DecodeError),
 
+    /// Error during cloud config validation.
     #[error("Error during cloud config validation: {0}")]
     Validation(String),
 
+    /// Error during TLS key/cert parsing.
     #[error("Error during key/cert parsing: {0}")]
     Tls(#[from] TlsError),
 }
@@ -158,8 +164,10 @@ impl AddressTranslator for CloudConfig {
 #[derive(Debug, Clone, Copy)]
 #[non_exhaustive]
 pub enum CloudTlsProvider {
+    /// OpenSSL 0.10 - backed TLS provider.
     #[cfg(feature = "openssl-010")]
     OpenSsl010,
+    /// Rustls 0.23 - backed TLS provider.
     #[cfg(feature = "rustls-023")]
     Rustls023,
 }

scylla/src/cloud/mod.rs

@@ -1,3 +1,5 @@
+//! Support for connecting to ScyllaDB Serverless Cloud.
+
 mod config;
 
 pub use config::CloudConfig;