From ee7538ef575b521927eec6a57ff5dc39526b5786 Mon Sep 17 00:00:00 2001
From: Ygor Souza <ygor.souza@protonmail.com>
Date: Sat, 13 Jan 2024 16:25:54 +0100
Subject: [PATCH] Document what read and write methods return

---
 src/lib.rs | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/src/lib.rs b/src/lib.rs
index 0face6b..c0aa725 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -534,6 +534,8 @@ impl HidDevice {
         self.inner.check_error()
     }
 
+    /// Write an Output report to a HID device.
+    ///
     /// The first byte of `data` must contain the Report ID. For
     /// devices which only support a single report, this must be set
     /// to 0x0. The remaining bytes contain the report data. Since
@@ -546,26 +548,37 @@ impl HidDevice {
     /// `write()` will send the data on the first OUT endpoint, if
     /// one exists. If it does not, it will send the data through
     /// the Control Endpoint (Endpoint 0).
+    ///
+    /// If successful, returns the actual number of bytes written.
     pub fn write(&self, data: &[u8]) -> HidResult<usize> {
         self.inner.write(data)
     }
 
+    /// Read an Input report from a HID device.
+    ///
     /// Input reports are returned to the host through the 'INTERRUPT IN'
     /// endpoint. The first byte will contain the Report number if the device
     /// uses numbered reports.
+    ///
+    /// If successful, returns the actual number of bytes read.
     pub fn read(&self, buf: &mut [u8]) -> HidResult<usize> {
         self.inner.read(buf)
     }
 
+    /// Read an Input report from a HID device with timeout.
+    ///
     /// Input reports are returned to the host through the 'INTERRUPT IN'
     /// endpoint. The first byte will contain the Report number if the device
     /// uses numbered reports. Timeout measured in milliseconds, set -1 for
     /// blocking wait.
+    ///
+    /// If successful, returns the actual number of bytes read.
     pub fn read_timeout(&self, buf: &mut [u8], timeout: i32) -> HidResult<usize> {
         self.inner.read_timeout(buf, timeout)
     }
 
     /// Send a Feature report to the device.
+    ///
     /// Feature reports are sent over the Control endpoint as a
     /// Set_Report transfer.  The first byte of `data` must contain the
     /// 'Report ID'. For devices which only support a single report, this must
@@ -576,13 +589,20 @@ impl HidDevice {
     /// `send_feature_report()`: 'the Report ID' (or 0x0, for devices which
     /// do not use numbered reports), followed by the report data (16 bytes).
     /// In this example, the length passed in would be 17.
+    ///
+    /// If successful, returns the actual number of bytes written.
     pub fn send_feature_report(&self, data: &[u8]) -> HidResult<()> {
         self.inner.send_feature_report(data)
     }
 
+    /// Get a feature report from a HID device.
+    ///
     /// Set the first byte of `buf` to the 'Report ID' of the report to be read.
     /// Upon return, the first byte will still contain the Report ID, and the
     /// report data will start in `buf[1]`.
+    ///
+    /// If successful, returns the number of bytes read plus one for the report ID (which is still
+    /// in the first byte).
     pub fn get_feature_report(&self, buf: &mut [u8]) -> HidResult<usize> {
         self.inner.get_feature_report(buf)
     }