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

clients/python/src/mxgateway/session.py

@@ -21,15 +21,18 @@ class Session:
         session_id: str,
         open_reply: pb.OpenSessionReply | None = None,
     ) -> None:
+        """Initialize a session bound to a client and gateway session id."""
         self.client = client
         self.session_id = session_id
         self.open_reply = open_reply
         self._closed = False
 
     async def __aenter__(self) -> "Session":
+        """Return self to support ``async with`` usage."""
         return self
 
     async def __aexit__(self, *_exc_info: object) -> None:
+        """Close the session when leaving an ``async with`` block."""
         await self.close()
 
     async def close(self, *, client_correlation_id: str = "") -> pb.CloseSessionReply:
@@ -74,6 +77,7 @@ class Session:
         )
 
     async def register(self, client_name: str, *, correlation_id: str = "") -> int:
+        """Invoke MXAccess `Register` and return the new `ServerHandle`."""
         reply = await self.invoke(
             pb.MxCommand(
                 kind=pb.MX_COMMAND_KIND_REGISTER,
@@ -84,6 +88,7 @@ class Session:
         return reply.register.server_handle
 
     async def unregister(self, server_handle: int, *, correlation_id: str = "") -> None:
+        """Invoke MXAccess `Unregister` for a previously registered `ServerHandle`."""
         await self.invoke(
             pb.MxCommand(
                 kind=pb.MX_COMMAND_KIND_UNREGISTER,
@@ -99,6 +104,7 @@ class Session:
         *,
         correlation_id: str = "",
     ) -> None:
+        """Invoke MXAccess `RemoveItem` for the given `ItemHandle`."""
         await self.invoke(
             pb.MxCommand(
                 kind=pb.MX_COMMAND_KIND_REMOVE_ITEM,
@@ -117,6 +123,7 @@ class Session:
         *,
         correlation_id: str = "",
     ) -> int:
+        """Invoke MXAccess `AddItem` and return the new `ItemHandle`."""
         reply = await self.invoke(
             pb.MxCommand(
                 kind=pb.MX_COMMAND_KIND_ADD_ITEM,
@@ -137,6 +144,7 @@ class Session:
         *,
         correlation_id: str = "",
     ) -> int:
+        """Invoke MXAccess `AddItem2` with item context and return the new `ItemHandle`."""
         reply = await self.invoke(
             pb.MxCommand(
                 kind=pb.MX_COMMAND_KIND_ADD_ITEM2,
@@ -157,6 +165,7 @@ class Session:
         *,
         correlation_id: str = "",
     ) -> None:
+        """Invoke MXAccess `Advise` to subscribe an existing `ItemHandle` to events."""
         await self.invoke(
             pb.MxCommand(
                 kind=pb.MX_COMMAND_KIND_ADVISE,
@@ -175,6 +184,7 @@ class Session:
         *,
         correlation_id: str = "",
     ) -> None:
+        """Invoke MXAccess `UnAdvise` to stop event delivery for an `ItemHandle`."""
         await self.invoke(
             pb.MxCommand(
                 kind=pb.MX_COMMAND_KIND_UN_ADVISE,
@@ -193,6 +203,7 @@ class Session:
         *,
         correlation_id: str = "",
     ) -> list[pb.SubscribeResult]:
+        """Invoke MXAccess `AddItemBulk` and return one result per tag address."""
         if tag_addresses is None:
             raise TypeError("tag_addresses is required")
         _ensure_bulk_size("tag_addresses", len(tag_addresses))
@@ -215,6 +226,7 @@ class Session:
         *,
         correlation_id: str = "",
     ) -> list[pb.SubscribeResult]:
+        """Invoke MXAccess `AdviseItemBulk` and return one result per item handle."""
         if item_handles is None:
             raise TypeError("item_handles is required")
         _ensure_bulk_size("item_handles", len(item_handles))
@@ -237,6 +249,7 @@ class Session:
         *,
         correlation_id: str = "",
     ) -> list[pb.SubscribeResult]:
+        """Invoke MXAccess `RemoveItemBulk` and return one result per item handle."""
         if item_handles is None:
             raise TypeError("item_handles is required")
         _ensure_bulk_size("item_handles", len(item_handles))
@@ -259,6 +272,7 @@ class Session:
         *,
         correlation_id: str = "",
     ) -> list[pb.SubscribeResult]:
+        """Invoke MXAccess `UnAdviseItemBulk` and return one result per item handle."""
         if item_handles is None:
             raise TypeError("item_handles is required")
         _ensure_bulk_size("item_handles", len(item_handles))
@@ -281,6 +295,7 @@ class Session:
         *,
         correlation_id: str = "",
     ) -> list[pb.SubscribeResult]:
+        """Invoke MXAccess `SubscribeBulk` and return one result per tag address."""
         if tag_addresses is None:
             raise TypeError("tag_addresses is required")
         _ensure_bulk_size("tag_addresses", len(tag_addresses))
@@ -303,6 +318,7 @@ class Session:
         *,
         correlation_id: str = "",
     ) -> list[pb.SubscribeResult]:
+        """Invoke MXAccess `UnsubscribeBulk` and return one result per item handle."""
         if item_handles is None:
             raise TypeError("item_handles is required")
         _ensure_bulk_size("item_handles", len(item_handles))
@@ -327,6 +343,7 @@ class Session:
         user_id: int = 0,
         correlation_id: str = "",
     ) -> None:
+        """Invoke MXAccess `Write` for an `ItemHandle` with the converted value."""
         await self.invoke(
             pb.MxCommand(
                 kind=pb.MX_COMMAND_KIND_WRITE,
@@ -350,6 +367,7 @@ class Session:
         user_id: int = 0,
         correlation_id: str = "",
     ) -> None:
+        """Invoke MXAccess `Write2` with both a value and a client-supplied timestamp."""
         await self.invoke(
             pb.MxCommand(
                 kind=pb.MX_COMMAND_KIND_WRITE2,
@@ -369,6 +387,7 @@ class Session:
         *,
         after_worker_sequence: int = 0,
     ) -> AsyncIterator[pb.MxEvent]:
+        """Return an async iterator of `MxEvent` messages for this session."""
         return self.client.stream_events_raw(
             pb.StreamEventsRequest(
                 session_id=self.session_id,