docs: cli: document proxies module

Signed-off-by: Artie Poole <stuart.poole@canonical.com>

Author: artiepoole

cli/src/proxies/control_proxy.rs

@@ -10,20 +10,94 @@
 //
 // You should have received a copy of the GNU General Public License along with this program.  If not, see http://www.gnu.org/licenses/.
 
+//! DBus proxy for the fpgad control interface.
+//!
+//! This module provides the auto-generated DBus proxy for the `com.canonical.fpgad.control`
+//! interface, which handles all write operations to the FPGA subsystem including:
+//! - Loading FPGA bitstreams
+//! - Applying device tree overlays
+//! - Removing overlays
+//! - Writing to FPGA manager properties
+//! - Setting FPGA flags
+//!
+//! The proxy is generated using the `zbus` crate's `#[proxy]` macro and provides
+//! type-safe, asynchronous access to the daemon's control interface.
+//!
+//! # DBus Interface Details
+//!
+//! - **Service**: `com.canonical.fpgad`
+//! - **Interface**: `com.canonical.fpgad.control`
+//! - **Object Path**: `/com/canonical/fpgad/control`
+//!
+//! # Usage
+//!
+//! ```rust,no_run
+//! use zbus::Connection;
+//! use control_proxy::ControlProxy;
+//!
+//! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
+//! let connection = Connection::system().await?;
+//! let proxy = ControlProxy::new(&connection).await?;
+//! let result = proxy.write_bitstream_direct(
+//!     "",
+//!     "fpga0",
+//!     "/lib/firmware/design.bit.bin",
+//!     ""
+//! ).await?;
+//! # Ok(())
+//! # }
+//! ```
+//!
+//! For detailed method documentation, see the daemon's
+//! [control interface documentation](../../../../daemon/comm/dbus/control_interface/index.html).
+
 use zbus::{Result, proxy};
+
+/// DBus proxy trait for the fpgad control interface.
+///
+/// This trait is auto-generated by the `#[proxy]` macro and provides methods to invoke
+/// the control interface methods on the fpgad daemon. All methods return `Result<String>`
+/// containing success messages or FpgadError messages.
+///
+/// See the main [module documentation](index.html) for usage examples.
 #[proxy(
     default_service = "com.canonical.fpgad",
     interface = "com.canonical.fpgad.control",
     default_path = "/com/canonical/fpgad/control"
 )]
 pub trait Control {
+    /// Set FPGA programming flags for a device.
+    ///
+    /// # Arguments
+    ///
+    /// * `platform_string` - Platform identifier (can be empty for auto-detection)
+    /// * `device_handle` - [Device handle](../../index.html#device-handles) (e.g., "fpga0")
+    /// * `flags` - Programming flags as a 32-bit unsigned integer
+    ///
+    /// # Returns: `Result<String>`
+    /// * `Ok(String)` - Success message with confirmation of flags set
+    /// * `Err(zbus::Error)` - DBus error or FpgadError.
+    ///   See [Error Handling](../../index.html#error-handling)
     async fn set_fpga_flags(
         &self,
         platform_string: &str,
         device_handle: &str,
         flags: u32,
     ) -> Result<String>;
 
+    /// Write a bitstream directly to an FPGA device.
+    ///
+    /// # Arguments
+    ///
+    /// * `platform_string` - Platform identifier (can be empty for auto-detection)
+    /// * `device_handle` - [Device handle](../../index.html#device-handles) (e.g., "fpga0")
+    /// * `bitstream_path_str` - Absolute path to the bitstream file
+    /// * `firmware_lookup_path` - Optional firmware search path (empty for default)
+    ///
+    /// # Returns: `Result<String>`
+    /// * `Ok(String)` - Success message confirming bitstream loaded
+    /// * `Err(zbus::Error)` - DBus error or FpgadError.
+    ///   See [Error Handling](../../index.html#error-handling)
     async fn write_bitstream_direct(
         &self,
         platform_string: &str,
@@ -32,6 +106,19 @@ pub trait Control {
         firmware_lookup_path: &str,
     ) -> Result<String>;
 
+    /// Apply a device tree overlay to the system.
+    ///
+    /// # Arguments
+    ///
+    /// * `platform_string` - Platform identifier string
+    /// * `overlay_handle` - [Overlay handle](../../index.html#overlay-handles) for the overlay directory
+    /// * `overlay_source_path` - Absolute path to the overlay file (.dtbo)
+    /// * `firmware_lookup_path` - Optional firmware search path (empty for default)
+    ///
+    /// # Returns: `Result<String>`
+    /// * `Ok(String)` - Success message confirming overlay applied
+    /// * `Err(zbus::Error)` - DBus error or FpgadError.
+    ///   See [Error Handling](../../index.html#error-handling)
     async fn apply_overlay(
         &self,
         platform_string: &str,
@@ -40,8 +127,42 @@ pub trait Control {
         firmware_lookup_path: &str,
     ) -> Result<String>;
 
+    /// Remove a device tree overlay from the system.
+    ///
+    /// # Arguments
+    ///
+    /// * `platform_str` - Platform identifier string
+    /// * `overlay_handle` - [Overlay handle](../../index.html#overlay-handles) to remove
+    ///
+    /// # Returns: `Result<String>`
+    /// * `Ok(String)` - Success message confirming overlay removed
+    /// * `Err(zbus::Error)` - DBus error or FpgadError.
+    ///   See [Error Handling](../../index.html#error-handling)
     async fn remove_overlay(&self, platform_str: &str, overlay_handle: &str) -> Result<String>;
 
+    /// Write a string value to an FPGA manager property.
+    ///
+    /// # Arguments
+    ///
+    /// * `property_path_str` - Full sysfs path to the property (must be under `/sys/class/fpga_manager/`)
+    /// * `data` - String data to write
+    ///
+    /// # Returns: `Result<String>`
+    /// * `Ok(String)` - Success message confirming write
+    /// * `Err(zbus::Error)` - DBus error or FpgadError.
+    ///   See [Error Handling](../../index.html#error-handling)
     async fn write_property(&self, property_path_str: &str, data: &str) -> Result<String>;
+
+    /// Write binary data to an FPGA manager property.
+    ///
+    /// # Arguments
+    ///
+    /// * `property_path_str` - Full sysfs path to the property (must be under `/sys/class/fpga_manager/`)
+    /// * `data` - Binary data to write as a byte slice
+    ///
+    /// # Returns: `Result<String>`
+    /// * `Ok(String)` - Success message confirming write
+    /// * `Err(zbus::Error)` - DBus error or FpgadError.
+    ///   See [Error Handling](../../index.html#error-handling)
     async fn write_property_bytes(&self, property_path_str: &str, data: &[u8]) -> Result<String>;
 }

cli/src/proxies/mod.rs

@@ -10,5 +10,37 @@
 //
 // You should have received a copy of the GNU General Public License along with this program.  If not, see http://www.gnu.org/licenses/.
 
+//! DBus proxy interfaces for the fpgad daemon.
+//!
+//! This module provides auto-generated DBus proxy traits that allow the CLI to communicate
+//! with the fpgad daemon over the system DBus. The proxies are generated using the `zbus`
+//! crate's `#[proxy]` macro and provide type-safe, asynchronous access to the daemon's
+//! DBus interfaces.
+//!
+//! # Modules
+//!
+//! - [`control_proxy`] - Write operations (load bitstreams, apply overlays, set properties)
+//! - [`status_proxy`] - Read-only operations (query device state, platform info, overlays)
+//!
+//! # DBus Service Information
+//!
+//! - **Service Name**: `com.canonical.fpgad`
+//! - **Control Interface**: `com.canonical.fpgad.control` at `/com/canonical/fpgad/control`
+//! - **Status Interface**: `com.canonical.fpgad.status` at `/com/canonical/fpgad/status`
+//!
+//! # Usage
+//!
+//! These proxies are used internally by the CLI's command handlers ([`load`], [`remove`],
+//! [`set`], [`status`]) to communicate with the fpgad daemon. The proxies handle DBus
+//! connection management and method call marshalling automatically.
+//!
+//! For more information on the DBus interfaces, see the
+//! [daemon DBus documentation](../../../daemon/comm/dbus/index.html).
+//!
+//! [`load`]: ../load/index.html
+//! [`remove`]: ../remove/index.html
+//! [`set`]: ../set/index.html
+//! [`status`]: ../status/index.html
+
 pub mod control_proxy;
 pub mod status_proxy;

cli/src/proxies/status_proxy.rs

@@ -10,21 +10,132 @@
 //
 // You should have received a copy of the GNU General Public License along with this program.  If not, see http://www.gnu.org/licenses/.
 
+//! DBus proxy for the fpgad status interface.
+//!
+//! This module provides the auto-generated DBus proxy for the `com.canonical.fpgad.status`
+//! interface, which handles all read-only operations for querying FPGA subsystem state:
+//! - Querying FPGA device states (operating, unknown, etc.)
+//! - Reading FPGA programming flags
+//! - Listing loaded device tree overlays
+//! - Getting platform compatibility strings
+//! - Checking overlay status
+//!
+//! The proxy is generated using the `zbus` crate's `#[proxy]` macro and provides
+//! type-safe, asynchronous access to the daemon's status interface.
+//!
+//! # DBus Interface Details
+//!
+//! - **Service**: `com.canonical.fpgad`
+//! - **Interface**: `com.canonical.fpgad.status`
+//! - **Object Path**: `/com/canonical/fpgad/status`
+//!
+//! # Usage
+//!
+//! ```rust,no_run
+//! use zbus::Connection;
+//! use status_proxy::StatusProxy;
+//!
+//! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
+//! let connection = Connection::system().await?;
+//! let proxy = StatusProxy::new(&connection).await?;
+//! let state = proxy.get_fpga_state("", "fpga0").await?;
+//! println!("FPGA state: {}", state);
+//! # Ok(())
+//! # }
+//! ```
+//!
+//! For detailed method documentation, see the daemon's
+//! [status interface documentation](../../../../daemon/comm/dbus/status_interface/index.html).
+
 use zbus::{Result, proxy};
+
+/// DBus proxy trait for the fpgad status interface.
+///
+/// This trait is auto-generated by the `#[proxy]` macro and provides methods to invoke
+/// the status interface methods on the fpgad daemon. All methods return `Result<String>`
+/// containing requested information or FpgadError messages.
+///
+/// See the main [module documentation](index.html) for usage examples.
 #[proxy(
     default_service = "com.canonical.fpgad",
     interface = "com.canonical.fpgad.status",
     default_path = "/com/canonical/fpgad/status"
 )]
 pub trait Status {
+    /// Get the current state of an FPGA device.
+    ///
+    /// Returns the device state such as "operating", "unknown", "write init", "write",
+    /// "write complete", or "write error".
+    ///
+    /// # Arguments
+    ///
+    /// * `platform_string` - Platform identifier (can be empty for auto-detection)
+    /// * `device_handle` - [Device handle](../../index.html#device-handles) (e.g., "fpga0")
+    ///
+    /// # Returns: `Result<String>`
+    /// * `Ok(String)` - Current state of the FPGA device
+    /// * `Err(zbus::Error)` - DBus error or FpgadError. See [Error Handling](../../index.html#error-handling)
     async fn get_fpga_state(&self, platform_string: &str, device_handle: &str) -> Result<String>;
+
+    /// Get the current programming flags for an FPGA device.
+    ///
+    /// Returns the flags as a hexadecimal string with no prefix (decimal value of 32 -> "20").
+    ///
+    /// # Arguments
+    ///
+    /// * `platform_string` - Platform identifier (can be empty for auto-detection)
+    /// * `device_handle` - [Device handle](../../index.html#device-handles) (e.g., "fpga0")
+    ///
+    /// # Returns: `Result<String>`
+    /// * `Ok(String)` - Current flags in hexadecimal format
+    /// * `Err(zbus::Error)` - DBus error or FpgadError. See [Error Handling](../../index.html#error-handling)
     async fn get_fpga_flags(&self, platform_string: &str, device_handle: &str) -> Result<String>;
+
+    /// Get the status of a specific device tree overlay.
+    ///
+    /// # Arguments
+    ///
+    /// * `platform_string` - Platform identifier string
+    /// * `overlay_handle` - [Overlay handle](../../index.html#overlay-handles) to query
+    ///
+    /// # Returns: `Result<String>`
+    /// * `Ok(String)` - Status information for the overlay
+    /// * `Err(zbus::Error)` - DBus error or FpgadError. See [Error Handling](../../index.html#error-handling)
     async fn get_overlay_status(
         &self,
         platform_string: &str,
         overlay_handle: &str,
     ) -> Result<String>;
+
+    /// Get a list of all loaded device tree overlays.
+    ///
+    /// Returns a newline-separated list of overlay handles.
+    ///
+    /// # Returns: `Result<String>`
+    /// * `Ok(String)` - Newline-separated list of overlay handles
+    /// * `Err(zbus::Error)` - DBus error or FpgadError. See [Error Handling](../../index.html#error-handling)
     async fn get_overlays(&self) -> Result<String>;
+
+    /// Get the platform compatibility string for an FPGA device.
+    ///
+    /// Returns the platform/compatibility string that identifies the hardware type
+    /// (e.g., "xlnx,zynqmp-pcap-fpga", "universal").
+    ///
+    /// # Arguments
+    ///
+    /// * `device_handle` - [Device handle](../../index.html#device-handles) (e.g., "fpga0")
+    ///
+    /// # Returns: `Result<String>`
+    /// * `Ok(String)` - Platform compatibility string
+    /// * `Err(zbus::Error)` - DBus error or FpgadError. See [Error Handling](../../index.html#error-handling)
     async fn get_platform_type(&self, device_handle: &str) -> Result<String>;
+
+    /// Get all FPGA devices and their platform strings.
+    ///
+    /// Returns a newline-separated list where each line is formatted as "device:platform".
+    ///
+    /// # Returns: `Result<String>`
+    /// * `Ok(String)` - Newline-separated list of "device:platform" pairs
+    /// * `Err(zbus::Error)` - DBus error or FpgadError. See [Error Handling](../../index.html#error-handling)
     async fn get_platform_types(&self) -> Result<String>;
 }