RSCBC-263: Indicate API stability via API doc

Author: chvck

sdk/couchbase/Cargo.toml

@@ -50,14 +50,8 @@ default = ["default-tls"]
 default-tls = ["rustls-tls"]
 rustls-tls = ["dep:tokio-rustls", "couchbase-core/rustls-tls", "dep:rustls-pemfile"]
 native-tls = ["dep:tokio-native-tls", "couchbase-core/native-tls"]
-
-# Volatile: This feature is subject to change at any time
-# Enables options for DNS-SRV bootstrap.
-unstable-dns-options = []
-
-# Uncomitted: This feature may change in the future
-# Allows explicit construction of the Error type e.g. for mocking purposes.
-unstable-error-construction = []
+# Note that we do not use feature flags to indicate API stability level.
+# Instead, unstable features are marked with comments indicating uncommitted or volatile stability levels.
 
 internal = []
 

sdk/couchbase/src/clients/cluster_client.rs

@@ -47,7 +47,6 @@ use std::time::Duration;
 
 use crate::authenticator::Authenticator;
 use crate::clients::tracing_client::{CouchbaseTracingClient, TracingClient, TracingClientBackend};
-#[cfg(feature = "unstable-dns-options")]
 use std::mem::take;
 
 pub(crate) struct ClusterClient {
@@ -70,10 +69,7 @@ impl ClusterClient {
         // the dns options out for resolve.
         // We could create a new type to pass into the backend connect functions but it just
         // seems unnecessary.
-        #[cfg(feature = "unstable-dns-options")]
         let dns_options = take(&mut opts.dns_options).map(couchbase_connstr::DnsConfig::from);
-        #[cfg(not(feature = "unstable-dns-options"))]
-        let dns_options = None;
 
         let resolved_conn_spec = resolve(conn_spec, dns_options).await?;
 

sdk/couchbase/src/error.rs

@@ -66,16 +66,12 @@ pub struct Error {
 }
 
 impl Error {
-    #[cfg(feature = "unstable-error-construction")]
+    /// Allows explicit construction of the Error type e.g. for mocking purposes.
+    /// **Uncommitted: This feature may change in the future**.
     pub fn new(kind: ErrorKind) -> Self {
         Self::new_internal(kind)
     }
 
-    #[cfg(not(feature = "unstable-error-construction"))]
-    pub(crate) fn new(kind: ErrorKind) -> Self {
-        Self::new_internal(kind)
-    }
-
     /// Returns the [`ErrorKind`] describing the category of this error.
     pub fn kind(&self) -> &ErrorKind {
         &self.kind
@@ -553,10 +549,7 @@ impl InvalidArgumentErrorKind {
         &self.msg
     }
 
-    /// Creates a new `InvalidArgumentErrorKind`.
-    ///
-    /// Only available with the `unstable-error-construction` feature.
-    #[cfg(feature = "unstable-error-construction")]
+    /// Creates a new `InvalidArgumentErrorKind`. **Uncommitted: This feature may change in the future**.
     pub fn new(arg: impl Into<Option<String>>, msg: impl Into<String>) -> Self {
         Self {
             msg: msg.into(),
@@ -589,10 +582,7 @@ impl FeatureNotAvailableErrorKind {
         self.msg.as_deref()
     }
 
-    /// Creates a new `FeatureNotAvailableErrorKind`.
-    ///
-    /// Only available with the `unstable-error-construction` feature.
-    #[cfg(feature = "unstable-error-construction")]
+    /// Creates a new `FeatureNotAvailableErrorKind`. **Uncommitted: This feature may change in the future**.
     pub fn new(feature: impl Into<String>, msg: impl Into<Option<String>>) -> Self {
         Self {
             feature: feature.into(),

sdk/couchbase/src/options/cluster_options.rs

@@ -81,8 +81,7 @@ pub struct ClusterOptions {
     pub http_options: HttpOptions,
     /// Configuration for the key-value (memcached) connections.
     pub kv_options: KvOptions,
-    /// DNS configuration. Only available with the `unstable-dns-options` feature.
-    #[cfg(feature = "unstable-dns-options")]
+    /// DNS configuration. **Volatile: This feature is subject to change at any time**.
     pub dns_options: Option<DnsOptions>,
     /// Configuration for the orphan response reporter.
     pub orphan_reporter_options: OrphanReporterOptions,
@@ -117,7 +116,6 @@ impl ClusterOptions {
             poller_options: PollerOptions::new(),
             http_options: HttpOptions::new(),
             kv_options: KvOptions::new(),
-            #[cfg(feature = "unstable-dns-options")]
             dns_options: None,
             orphan_reporter_options: OrphanReporterOptions::new(),
             default_retry_strategy: None,
@@ -160,10 +158,7 @@ impl ClusterOptions {
         self
     }
 
-    /// Sets the DNS configuration.
-    ///
-    /// Only available with the `unstable-dns-options` feature.
-    #[cfg(feature = "unstable-dns-options")]
+    /// Sets the DNS configuration. **Volatile: This feature is subject to change at any time**.
     pub fn dns_options(mut self, dns_options: DnsOptions) -> Self {
         self.dns_options = Some(dns_options);
         self
@@ -685,19 +680,16 @@ impl Display for TlsOptions {
     }
 }
 
-/// Custom DNS resolver configuration.
-///
-/// Only available with the `unstable-dns-options` feature.
+/// Custom DNS resolver configuration.  **Volatile: This feature is subject to change at any time**.
 #[derive(Clone, Debug, PartialEq)]
 #[non_exhaustive]
-#[cfg(feature = "unstable-dns-options")]
 pub struct DnsOptions {
     /// The DNS server address to use for SRV and A/AAAA lookups.
     pub namespace: SocketAddr,
     /// Timeout for DNS resolution.
     pub timeout: Option<Duration>,
 }
-#[cfg(feature = "unstable-dns-options")]
+
 impl DnsOptions {
     /// Creates a new `DnsOptions` with the given DNS server address.
     pub fn new(namespace: SocketAddr) -> Self {
@@ -713,7 +705,6 @@ impl DnsOptions {
         self
     }
 }
-#[cfg(feature = "unstable-dns-options")]
 impl From<DnsOptions> for couchbase_connstr::DnsConfig {
     fn from(opts: DnsOptions) -> Self {
         couchbase_connstr::DnsConfig {