Lack of documentation on Read trait

[Mubelotix]

I have come to the need of implementing hyper::rt::Read on a custom struct. It seems to me that its documentation has been copy-pasted from tokio's AsyncRead, except it's outdated since the signature has been changed. For some reason not stated in the doc, a ReadBufCursor is used instead of the original ReadBuf. Now, I simply couldn't understand from the doc how I was supposed to implement Read, considering ReadBufCursor only has 2 unsafe methods and isn't too-well documented either. I would greatly appreciate further official guidance on implementing the Read trait. Thank you for making hyper

[seanmonstar]

Agreed, it is lacking in documentation. That'd be helpful to improve.

Regarding the ReadBufCursor, that comes from lessons learned in Tokio: only passing a &mut Thing allows the receiver to do something like *buf = Box::leak(blah), and then the underlying buffer pointer is different. You can see a similar "improvement" in the unstable std::io::BorrowedBuf and BorrowedCursor.

It only has the minimum methods in hyper because I wanted "needs" to drive adding methods, instead of trying to guess which might be useful.