Document what write() and read() functions return

[JonathanLindsey]

What do the HidDevice::write() and HidDevice::read() functions return when it is successful?

It's a usize type but what does it mean? My guess is it's how many bytes were written from or read into the buffer. But would the length of the buffer ever not equal the return value?

Nothing about the return value is documented with the functions.

[YgorSouza]

Yes, the usize is the number of bytes read or written. It's not necessarily equal to the size of the buffer, because HIDAPI tries to read a single Input report or write a single Output report, regardless of the size of the buffer that was passed in. Also, if you set nonblocking mode, it might return 0 if there is nothing to read. In that case it will return Ok(0), not an error.

This is documented more thoroughly in the original C library:

https://github.com/libusb/hidapi/blob/86b056fe70eff4befe91559785836328e694e825/hidapi/hidapi.h#L350-L370

This crate copies that doc, but only partially:

https://github.com/ruabmbua/hidapi-rs/blob/78f273800a7e9fc7f428e45d2cfebaf7b44862c1/src/lib.rs#L536-L541

I guess it would be a good idea to port more of the C doc here, namely the @brief and @returns sections. I'll see if I can make a PR if I have some time.

[ruabmbua]

Sure, I think having better documentation on our own is now more important, since the library will not be necessarily a wrapper over the hidapi C library in the future.

For now, if you need to know anything, please look at the hidapi C library documentation. We mirror the API pretty much 1:1.