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

clients/rust/src/error.rs

@@ -1,75 +1,136 @@
+//! Error types surfaced by the Rust client.
+//!
+//! [`Error`] is the umbrella enum returned by every async wrapper. It
+//! classifies `tonic::Status` codes (auth, timeout, cancellation) and folds
+//! gateway protocol failures and command-level rejections into structured
+//! variants. Credentials embedded in status messages are scrubbed before the
+//! message reaches a caller.
+
 use thiserror::Error as ThisError;
 use tonic::Code;
 
 use crate::generated::mxaccess_gateway::v1::{MxCommandReply, ProtocolStatus, ProtocolStatusCode};
 
+/// Top-level error type returned by the Rust client wrappers.
+///
+/// The variants distinguish transport/setup failures, classified gRPC status
+/// codes, gateway protocol-level failures (`OpenSession`, `CloseSession`),
+/// and command-level rejections that surface a populated [`MxCommandReply`].
 #[derive(Debug, ThisError)]
 pub enum Error {
+    /// Endpoint URL could not be parsed or its TLS material could not be
+    /// loaded.
     #[error("invalid gateway endpoint `{endpoint}`: {detail}")]
-    InvalidEndpoint { endpoint: String, detail: String },
+    InvalidEndpoint {
+        /// Endpoint string supplied by the caller.
+        endpoint: String,
+        /// Human-readable explanation of the parse/load failure.
+        detail: String,
+    },
 
+    /// A caller-provided argument failed local validation before any RPC
+    /// was dispatched (for example, a bulk command exceeding the size cap).
     #[error("invalid argument `{name}`: {detail}")]
-    InvalidArgument { name: String, detail: String },
+    InvalidArgument {
+        /// Name of the offending argument.
+        name: String,
+        /// Reason the argument was rejected.
+        detail: String,
+    },
 
+    /// Tonic transport-level failure (DNS, connect, TLS handshake).
     #[error("gateway transport error: {0}")]
     Transport(#[from] tonic::transport::Error),
 
+    /// Server returned `Unauthenticated` — the API key was missing or
+    /// rejected.
     #[error("authentication failed: {message}")]
     Authentication {
+        /// Redacted server-supplied detail message.
         message: String,
+        /// Original `tonic::Status` for callers that need the full context.
         #[source]
         status: Box<tonic::Status>,
     },
 
+    /// Server returned `PermissionDenied` — the API key is valid but lacks
+    /// the required scope.
     #[error("authorization failed: {message}")]
     Authorization {
+        /// Redacted server-supplied detail message.
         message: String,
+        /// Original `tonic::Status`.
         #[source]
         status: Box<tonic::Status>,
     },
 
+    /// Server returned `DeadlineExceeded`. Usually the per-call deadline
+    /// configured via [`crate::options::ClientOptions::with_call_timeout`].
     #[error("gateway call timed out: {message}")]
     Timeout {
+        /// Redacted server-supplied detail message.
         message: String,
+        /// Original `tonic::Status`.
         #[source]
         status: Box<tonic::Status>,
     },
 
+    /// Server (or client) cancelled the call before a reply was produced.
     #[error("gateway call cancelled: {message}")]
     Cancelled {
+        /// Redacted server-supplied detail message.
         message: String,
+        /// Original `tonic::Status`.
         #[source]
         status: Box<tonic::Status>,
     },
 
+    /// Any other `tonic::Status` that did not match a more specific variant.
     #[error("gateway status error: {0}")]
     Status(Box<tonic::Status>),
 
+    /// Gateway accepted the call but the worker reply carried a non-OK
+    /// protocol status. The wrapped [`CommandError`] preserves the full
+    /// reply so callers can inspect the worker's status payload.
     #[error("gateway command failed: {0}")]
     Command(#[from] Box<CommandError>),
 
+    /// Protocol-level operation (open/close session) returned a non-OK
+    /// [`ProtocolStatus`] envelope.
     #[error("gateway {operation} failed: {code:?}: {message}")]
     ProtocolStatus {
+        /// Operation name, e.g. `"open session"`.
         operation: &'static str,
+        /// Decoded protocol status code from the server.
         code: ProtocolStatusCode,
+        /// Detail message from the server.
         message: String,
     },
 }
 
+/// Wrapper around an [`MxCommandReply`] whose `protocol_status` reported a
+/// non-OK code.
+///
+/// The wrapper is heap-allocated inside [`Error::Command`] to keep the
+/// containing enum small. Callers can recover the reply with
+/// [`CommandError::reply`] or [`CommandError::into_reply`].
 #[derive(Clone, Debug)]
 pub struct CommandError {
     reply: MxCommandReply,
 }
 
 impl CommandError {
+    /// Wrap an already-failed command reply.
     pub fn new(reply: MxCommandReply) -> Self {
         Self { reply }
     }
 
+    /// Borrow the underlying reply (correlation id, status, payload).
     pub fn reply(&self) -> &MxCommandReply {
         &self.reply
     }
 
+    /// Consume the error and return the underlying reply.
     pub fn into_reply(self) -> MxCommandReply {
         self.reply
     }
@@ -118,6 +179,13 @@ impl From<tonic::Status> for Error {
     }
 }
 
+/// Promote a non-OK protocol status carried inside an [`MxCommandReply`]
+/// to an [`Error::Command`].
+///
+/// # Errors
+///
+/// Returns [`Error::Command`] when `reply.protocol_status` is missing or
+/// reports any code other than [`ProtocolStatusCode::Ok`].
 pub fn ensure_command_success(reply: MxCommandReply) -> Result<MxCommandReply, Error> {
     let code = reply
         .protocol_status
@@ -132,6 +200,13 @@ pub fn ensure_command_success(reply: MxCommandReply) -> Result<MxCommandReply, E
     }
 }
 
+/// Validate a [`ProtocolStatus`] envelope returned by an open/close-session
+/// reply.
+///
+/// # Errors
+///
+/// Returns [`Error::ProtocolStatus`] tagged with `operation` when `status`
+/// is missing or reports any code other than [`ProtocolStatusCode::Ok`].
 pub fn ensure_protocol_success(
     operation: &'static str,
     status: Option<&ProtocolStatus>,