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

clients/rust/src/auth.rs

@@ -1,3 +1,7 @@
+//! API-key wrapper and the `tonic` interceptor that attaches it as a Bearer
+//! token on every outbound gRPC call. The wrapper redacts its inner value in
+//! `Debug`/`Display` so logs never leak the secret.
+
 use std::fmt;
 
 use tonic::metadata::MetadataValue;
@@ -5,14 +9,21 @@ use tonic::service::Interceptor;
 use tonic::{Request, Status};
 
 /// API key wrapper that avoids exposing raw credentials in formatted output.
+///
+/// Use [`ApiKey::expose_secret`] when the underlying string is genuinely
+/// needed (for example, building the `authorization` header).
 #[derive(Clone, Eq, PartialEq)]
 pub struct ApiKey(String);
 
 impl ApiKey {
+    /// Construct an [`ApiKey`] from the raw `mxgw_<key-id>_<secret>` string
+    /// returned by the gateway's `apikey` admin command.
     pub fn new(value: impl Into<String>) -> Self {
         Self(value.into())
     }
 
+    /// Return the raw key value. Callers must not log or otherwise persist
+    /// the result.
     pub fn expose_secret(&self) -> &str {
         &self.0
     }
@@ -40,6 +51,9 @@ pub struct AuthInterceptor {
 }
 
 impl AuthInterceptor {
+    /// Build an interceptor that injects the supplied API key on every
+    /// request. Pass `None` to disable authentication (useful for local
+    /// development against a gateway with `Authentication:Required = false`).
     pub fn new(api_key: Option<ApiKey>) -> Self {
         Self { api_key }
     }