Add idiomatic documentation to Go, Java, Python, and Rust clients

clients/rust/src/options.rs

@@ -1,9 +1,19 @@
+//! Connection options shared by [`crate::client::GatewayClient`] and
+//! [`crate::galaxy::GalaxyClient`]. Build with [`ClientOptions::new`] and a
+//! chain of `with_*` setters; the `Debug` impl redacts the API key.
+
 use std::fmt;
 use std::path::PathBuf;
 use std::time::Duration;
 
 use crate::auth::ApiKey;
 
+/// Configuration for connecting to a gateway endpoint.
+///
+/// Defaults are 10s connect timeout, 30s call timeout, no streaming timeout,
+/// and plaintext (h2c) transport. Set [`ClientOptions::with_plaintext`] to
+/// `false` and supply [`ClientOptions::with_ca_file`] / a server-name override
+/// for TLS deployments.
 #[derive(Clone)]
 pub struct ClientOptions {
     endpoint: String,
@@ -17,6 +27,8 @@ pub struct ClientOptions {
 }
 
 impl ClientOptions {
+    /// Build options for the supplied gateway endpoint URL (for example,
+    /// `http://127.0.0.1:5000`). Other settings take their defaults.
     pub fn new(endpoint: impl Into<String>) -> Self {
         Self {
             endpoint: endpoint.into(),
@@ -30,69 +42,91 @@ impl ClientOptions {
         }
     }
 
+    /// Attach an API key. The key flows through [`crate::auth::AuthInterceptor`]
+    /// as the Bearer token on every request.
     pub fn with_api_key(mut self, api_key: ApiKey) -> Self {
         self.api_key = Some(api_key);
         self
     }
 
+    /// Toggle h2c (plaintext) vs TLS. `true` (the default) skips the TLS
+    /// handshake and is suitable for loopback development.
     pub fn with_plaintext(mut self, plaintext: bool) -> Self {
         self.plaintext = plaintext;
         self
     }
 
+    /// Trust roots PEM bundle for TLS connections. Ignored when
+    /// `plaintext` is `true`.
     pub fn with_ca_file(mut self, ca_file: impl Into<PathBuf>) -> Self {
         self.ca_file = Some(ca_file.into());
         self
     }
 
+    /// Override the SNI/server name used during the TLS handshake. Useful
+    /// when the dial-target host name does not match the certificate.
     pub fn with_server_name_override(mut self, server_name_override: impl Into<String>) -> Self {
         self.server_name_override = Some(server_name_override.into());
         self
     }
 
+    /// Maximum time the transport waits for the initial TCP/TLS connection.
     pub fn with_connect_timeout(mut self, connect_timeout: Duration) -> Self {
         self.connect_timeout = connect_timeout;
         self
     }
 
+    /// Per-call deadline applied to every unary RPC. Streaming RPCs use
+    /// [`ClientOptions::with_stream_timeout`] instead.
     pub fn with_call_timeout(mut self, call_timeout: Duration) -> Self {
         self.call_timeout = call_timeout;
         self
     }
 
+    /// Optional deadline applied to streaming RPCs (for example,
+    /// `StreamEvents`). Without a stream timeout the stream lives until the
+    /// caller drops it or the server closes it.
     pub fn with_stream_timeout(mut self, stream_timeout: Duration) -> Self {
         self.stream_timeout = Some(stream_timeout);
         self
     }
 
+    /// Configured endpoint URL.
     pub fn endpoint(&self) -> &str {
         &self.endpoint
     }
 
+    /// Configured API key, if any.
     pub fn api_key(&self) -> Option<&ApiKey> {
         self.api_key.as_ref()
     }
 
+    /// Whether the transport runs in plaintext (h2c) mode.
     pub fn plaintext(&self) -> bool {
         self.plaintext
     }
 
+    /// Optional CA bundle path used to validate the server certificate.
     pub fn ca_file(&self) -> Option<&PathBuf> {
         self.ca_file.as_ref()
     }
 
+    /// Optional SNI / server-name override for TLS handshakes.
     pub fn server_name_override(&self) -> Option<&str> {
         self.server_name_override.as_deref()
     }
 
+    /// Connect timeout used during transport setup.
     pub fn connect_timeout(&self) -> Duration {
         self.connect_timeout
     }
 
+    /// Per-call timeout for unary RPCs.
     pub fn call_timeout(&self) -> Duration {
         self.call_timeout
     }
 
+    /// Optional per-call timeout for streaming RPCs.
     pub fn stream_timeout(&self) -> Option<Duration> {
         self.stream_timeout
     }