frame/types: document consistencies

Author: wprzytula

scylla-cql/src/frame/types.rs

@@ -16,25 +16,45 @@ use std::str;
 use thiserror::Error;
 use uuid::Uuid;
 
+/// A setting that defines a successful write or read by the number of cluster replicas
+/// that acknowledge the write or respond to the read request, respectively.
+/// See [ScyllaDB docs](https://docs.scylladb.com/manual/stable/cql/consistency.html)
+/// for more detailed description and guidelines.
 #[derive(Debug, Copy, Clone, Default, PartialEq, Eq, PartialOrd, Ord)]
 #[cfg_attr(feature = "serde", derive(serde::Deserialize))]
 #[cfg_attr(feature = "serde", serde(rename_all = "SCREAMING_SNAKE_CASE"))]
 #[repr(u16)]
 pub enum Consistency {
+    /// **Write-only**. Closest replica, as determined by the
+    /// [Snitch](https://docs.scylladb.com/manual/stable/reference/glossary.html#term-Snitch),
+    /// must respond. If all replica nodes are down, write succeeds after a hinted handoff.
+    /// Provides low latency, guarantees writes never fail.
     Any = 0x0000,
+    /// The closest replica as determined by the Snitch must respond. Consistency requirements
+    /// are not too strict.
     One = 0x0001,
+    /// The closest two replicas as determined by the Snitch must respond.
     Two = 0x0002,
+    /// The closest three replicas as determined by the Snitch must respond.
     Three = 0x0003,
+    /// A simple majority of all replicas across all datacenters must respond.
+    /// This CL allows for some level of failure.
     Quorum = 0x0004,
+    /// _All_ replicas in the cluster must respond. May cause performance issues.
     All = 0x0005,
+    /// Same as [QUORUM](Consistency::Quorum), but confined to the same datacenter as the coordinator.
     #[default]
     LocalQuorum = 0x0006,
+    /// **Write-only**. A simple majority in each datacenter must respond.
     EachQuorum = 0x0007,
+    /// Same as [ONE](Consistency::One), but confined to the local datacenter.
     LocalOne = 0x000A,
 
     // Apparently, Consistency can be set to Serial or LocalSerial in SELECT statements
     // to make them use Paxos.
+    /// **Read-only**. Returns results with the most recent data. Including uncommitted in-flight LWTs.
     Serial = 0x0008,
+    /// **Read-only**. Same as [SERIAL](Consistency::Serial), but confined to a local datacenter.
     LocalSerial = 0x0009,
 }
 
@@ -62,12 +82,18 @@ impl TryFrom<u16> for Consistency {
     }
 }
 
+/// [Consistency] for Lightweight Transactions (LWTs).
+///
+/// [SerialConsistency] sets the consistency level for the serial phase of conditional updates.
+/// This option will be ignored for anything else that a conditional update/insert.
 #[derive(Debug, Copy, Clone, PartialEq, Eq, PartialOrd, Ord)]
 #[cfg_attr(feature = "serde", derive(serde::Deserialize))]
 #[cfg_attr(feature = "serde", serde(rename_all = "SCREAMING_SNAKE_CASE"))]
 #[repr(i16)]
 pub enum SerialConsistency {
+    /// Guarantees linearizable semantics across the whole cluster.
     Serial = 0x0008,
+    /// Guarantees linearizable semantics in a local datacenter.
     LocalSerial = 0x0009,
 }
 
@@ -93,6 +119,7 @@ impl Consistency {
     }
 }
 
+/// Error returned when a serial consistency what expected, yet got another kind of consistency.
 #[derive(Debug, Error)]
 #[error("Expected Consistency Serial or LocalSerial, got: {0}")]
 pub struct NonSerialConsistencyError(Consistency);