-
Notifications
You must be signed in to change notification settings - Fork 160
Description
Following a discussion in #276
Speaking from experience, I think it is quite difficult to understand this library at a first glance, even if you are familiar with how io_uring
works.
The two main issues I had was that the crate-level documentation says to "read the manpage" but does not go into any detail of what manpages to read or how this library differs from the raw io_uring
interface. I think this would be fine if the way this library was intended to be used was exactly the same or at least closely related to how one would use the io_uring
interface, but since that is not the case it was very confusing.
I feel that this library is much closer to the liburing
library than the io_uring
interface. The way that opcodes are constructed, how entries are pushed onto and pulled of of the queues, they are all much more like liburing
. However, very little of the documentation (only 3 instances) even mention liburing
. This makes it harder for newcomers to understand that they should be looking at the liburing
man pages.
So I think that there are two ways to make improvements here: more detailed documentation or more examples. It seems like this library is taking the position that it should only document a "summary of parameters", but I still feel that it can always be improved by adding pointers to specific man pages.
The other way is more examples, which #268 seems to address. Even if someone experienced with liburing
comes along to this library, the API does not directly translate in some places. Examples are beneficial to everyone! Even just a bit on the crate-level docs showing how a single opcode is built and pushed onto the submission queue would be super helpful. I'm willing to make a PR if you think that this is a good idea.