Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Documentation should point to liburing + examples #286

Open
connortsui20 opened this issue May 13, 2024 · 0 comments
Open

Documentation should point to liburing + examples #286

connortsui20 opened this issue May 13, 2024 · 0 comments

Comments

@connortsui20
Copy link
Contributor

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

1 participant