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

clients/rust/src/value.rs

@@ -1,3 +1,13 @@
+//! Rust-shaped wrappers around the wire `MxValue`, `MxArray`, and
+//! `MxStatusProxy` types.
+//!
+//! [`MxValue`] keeps both the original protobuf message and a friendly
+//! [`MxValueProjection`] enum, so callers can pass values through the wire
+//! without losing information while still being able to pattern-match on
+//! the typed variant. The same split applies to [`MxArrayValue`] and
+//! [`MxArrayProjection`]. [`MxStatus`] wraps the MXAccess `MxStatusProxy`
+//! status envelope.
+
 use crate::generated::mxaccess_gateway::v1::mx_array::Values;
 use crate::generated::mxaccess_gateway::v1::mx_value::Kind;
 use crate::generated::mxaccess_gateway::v1::{
@@ -6,6 +16,12 @@ use crate::generated::mxaccess_gateway::v1::{
     StringArray, TimestampArray,
 };
 
+/// Owned `MxValue` carrying both the raw protobuf message and a typed
+/// [`MxValueProjection`] view.
+///
+/// The constructors set both `data_type` and `variant_type` to the values
+/// the worker expects so values built locally round-trip through MXAccess
+/// without surprises.
 #[derive(Clone, Debug, PartialEq)]
 pub struct MxValue {
     raw: ProtoMxValue,
@@ -13,11 +29,14 @@ pub struct MxValue {
 }
 
 impl MxValue {
+    /// Wrap a protobuf [`ProtoMxValue`] and compute its
+    /// [`MxValueProjection`].
     pub fn from_proto(raw: ProtoMxValue) -> Self {
         let projection = MxValueProjection::from_proto(&raw);
         Self { raw, projection }
     }
 
+    /// Build a boolean `MxValue` (`MxDataType::Boolean`, `VT_BOOL`).
     pub fn bool(value: bool) -> Self {
         Self::from_proto(ProtoMxValue {
             data_type: MxDataType::Boolean as i32,
@@ -27,6 +46,7 @@ impl MxValue {
         })
     }
 
+    /// Build a 32-bit integer `MxValue` (`MxDataType::Integer`, `VT_I4`).
     pub fn int32(value: i32) -> Self {
         Self::from_proto(ProtoMxValue {
             data_type: MxDataType::Integer as i32,
@@ -36,6 +56,7 @@ impl MxValue {
         })
     }
 
+    /// Build a 64-bit integer `MxValue` (`MxDataType::Integer`, `VT_I8`).
     pub fn int64(value: i64) -> Self {
         Self::from_proto(ProtoMxValue {
             data_type: MxDataType::Integer as i32,
@@ -45,6 +66,7 @@ impl MxValue {
         })
     }
 
+    /// Build a 32-bit float `MxValue` (`MxDataType::Float`, `VT_R4`).
     pub fn float(value: f32) -> Self {
         Self::from_proto(ProtoMxValue {
             data_type: MxDataType::Float as i32,
@@ -54,6 +76,7 @@ impl MxValue {
         })
     }
 
+    /// Build a 64-bit float `MxValue` (`MxDataType::Double`, `VT_R8`).
     pub fn double(value: f64) -> Self {
         Self::from_proto(ProtoMxValue {
             data_type: MxDataType::Double as i32,
@@ -63,6 +86,7 @@ impl MxValue {
         })
     }
 
+    /// Build a string `MxValue` (`MxDataType::String`, `VT_BSTR`).
     pub fn string(value: impl Into<String>) -> Self {
         Self::from_proto(ProtoMxValue {
             data_type: MxDataType::String as i32,
@@ -72,14 +96,18 @@ impl MxValue {
         })
     }
 
+    /// Borrow the underlying protobuf message exactly as it will travel
+    /// over the wire.
     pub fn raw(&self) -> &ProtoMxValue {
         &self.raw
     }
 
+    /// Borrow the typed projection.
     pub fn projection(&self) -> &MxValueProjection {
         &self.projection
     }
 
+    /// Consume the wrapper and return the underlying protobuf message.
     pub fn into_proto(self) -> ProtoMxValue {
         self.raw
     }
@@ -97,18 +125,35 @@ impl From<ProtoMxValue> for MxValue {
     }
 }
 
+/// Typed view over an [`MxValue`].
+///
+/// Mirrors the `MxValue::Kind` oneof on the wire, plus a [`MxValueProjection::Null`]
+/// variant for `is_null=true` and a [`MxValueProjection::Unset`] variant for
+/// values that arrive without a `kind` set.
 #[derive(Clone, Debug, PartialEq)]
 pub enum MxValueProjection {
+    /// No `kind` was present on the wire.
     Unset,
+    /// `is_null = true` on the wire.
     Null,
+    /// Boolean value.
     Bool(bool),
+    /// 32-bit signed integer value.
     Int32(i32),
+    /// 64-bit signed integer value.
     Int64(i64),
+    /// 32-bit float value.
     Float(f32),
+    /// 64-bit float value.
     Double(f64),
+    /// UTF-8 string value.
     String(String),
+    /// Wall-clock timestamp.
     Timestamp(prost_types::Timestamp),
+    /// Array value carrying a homogeneous element type.
     Array(MxArrayValue),
+    /// Opaque variant payload that the gateway could not project to a typed
+    /// scalar.
     Raw(Vec<u8>),
 }
 
@@ -133,6 +178,8 @@ impl MxValueProjection {
     }
 }
 
+/// Owned `MxArray` carrying both the raw protobuf message and a typed
+/// [`MxArrayProjection`] view of its elements.
 #[derive(Clone, Debug, PartialEq)]
 pub struct MxArrayValue {
     raw: MxArray,
@@ -140,11 +187,14 @@ pub struct MxArrayValue {
 }
 
 impl MxArrayValue {
+    /// Wrap a protobuf [`MxArray`] and compute its
+    /// [`MxArrayProjection`].
     pub fn from_proto(raw: MxArray) -> Self {
         let projection = MxArrayProjection::from_proto(&raw);
         Self { raw, projection }
     }
 
+    /// Build a one-dimensional string array (`VT_ARRAY|VT_BSTR`).
     pub fn string(values: Vec<String>) -> Self {
         Self::from_proto(MxArray {
             element_data_type: MxDataType::String as i32,
@@ -155,25 +205,40 @@ impl MxArrayValue {
         })
     }
 
+    /// Borrow the underlying protobuf array message.
     pub fn raw(&self) -> &MxArray {
         &self.raw
     }
 
+    /// Borrow the typed projection of the array's elements.
     pub fn projection(&self) -> &MxArrayProjection {
         &self.projection
     }
 }
 
+/// Typed view over an [`MxArrayValue`].
+///
+/// Each variant matches the corresponding `MxArray::Values` oneof arm on
+/// the wire.
 #[derive(Clone, Debug, PartialEq)]
 pub enum MxArrayProjection {
+    /// No `values` oneof was present on the wire.
     Unset,
+    /// Boolean elements.
     Bool(Vec<bool>),
+    /// 32-bit signed integer elements.
     Int32(Vec<i32>),
+    /// 64-bit signed integer elements.
     Int64(Vec<i64>),
+    /// 32-bit float elements.
     Float(Vec<f32>),
+    /// 64-bit float elements.
     Double(Vec<f64>),
+    /// UTF-8 string elements.
     String(Vec<String>),
+    /// Timestamp elements.
     Timestamp(Vec<prost_types::Timestamp>),
+    /// Opaque variant payloads, one per element.
     Raw(Vec<Vec<u8>>),
 }
 
@@ -195,44 +260,57 @@ impl MxArrayProjection {
     }
 }
 
+/// Typed wrapper around the MXAccess `MxStatusProxy` envelope, the
+/// per-value status that accompanies every `OnDataChange`/`Read` reply.
 #[derive(Clone, Debug, PartialEq)]
 pub struct MxStatus {
     raw: MxStatusProxy,
 }
 
 impl MxStatus {
+    /// Wrap a protobuf [`MxStatusProxy`].
     pub fn from_proto(raw: MxStatusProxy) -> Self {
         Self { raw }
     }
 
+    /// Borrow the underlying protobuf message.
     pub fn raw(&self) -> &MxStatusProxy {
         &self.raw
     }
 
+    /// `MXSTATUS_PROXY.Success` flag (0 = error, non-zero = good/warning).
     pub fn success(&self) -> i32 {
         self.raw.success
     }
 
+    /// Decode the status category, or `None` if the wire value is not a
+    /// known [`MxStatusCategory`].
     pub fn category(&self) -> Option<MxStatusCategory> {
         MxStatusCategory::try_from(self.raw.category).ok()
     }
 
+    /// Decode the source (provider, gateway, worker) that flagged the
+    /// status, or `None` for unknown values.
     pub fn detected_by(&self) -> Option<MxStatusSource> {
         MxStatusSource::try_from(self.raw.detected_by).ok()
     }
 
+    /// `MXSTATUS_PROXY.Detail` numeric reason code.
     pub fn detail(&self) -> i32 {
         self.raw.detail
     }
 
+    /// Raw, undecoded category integer (useful for forward compatibility).
     pub fn raw_category(&self) -> i32 {
         self.raw.raw_category
     }
 
+    /// Raw, undecoded detected-by integer.
     pub fn raw_detected_by(&self) -> i32 {
         self.raw.raw_detected_by
     }
 
+    /// Optional human-readable diagnostic from MXAccess.
     pub fn diagnostic_text(&self) -> &str {
         &self.raw.diagnostic_text
     }