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.
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_uringworks.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_uringinterface. 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 theio_uringinterface, but since that is not the case it was very confusing.I feel that this library is much closer to the
liburinglibrary than theio_uringinterface. The way that opcodes are constructed, how entries are pushed onto and pulled of of the queues, they are all much more likeliburing. However, very little of the documentation (only 3 instances) even mentionliburing. This makes it harder for newcomers to understand that they should be looking at theliburingman 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
liburingcomes 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.