A bit more documentation fixes (#347)

* Fix the description of TimeoutFlags::ETIME_SUCCESS (#342)

* fix opcode::Timeout docs

`TimeoutFlags::TIMEOUT` does not exists, pull request that added it
probably meant `TimeoutFlags::MULTISHOT`, but it's not in scope either
so fix for that too

* document submit_with_args a bit more

* fix docs for TimeoutFlags

Constants referred by docs are available directly, without `types::`
prefix

Author: pacak

src/opcode.rs

@@ -543,8 +543,8 @@ opcode! {
         timespec: { *const types::Timespec },
         ;;
         /// `count` may contain a completion event count.
-        /// If [`TimeoutFlags::TIMEOUT`] is set in `flags`, this is the number of repeats. A value of 0 means the timeout is
-        /// indefinite and can only be stopped by a removal request.
+        /// If [`TimeoutFlags::MULTISHOT`](types::TimeoutFlags::MULTISHOT) is set in `flags`, this is the number of repeats.
+        /// A value of 0 means the timeout is indefinite and can only be stopped by a removal request.
         count: u32 = 0,
 
         flags: types::TimeoutFlags = types::TimeoutFlags::empty()

src/submit.rs

@@ -142,6 +142,11 @@ impl<'a> Submitter<'a> {
         unsafe { self.enter::<libc::sigset_t>(len as _, want as _, flags, None) }
     }
 
+    /// Submit all queued submission queue events to the kernel and wait for at least `want`
+    /// completion events to complete with additional options
+    ///
+    /// You can specify a set of signals to mask and a timeout for operation, see
+    /// [`SubmitArgs`](types::SubmitArgs) for more details
     pub fn submit_with_args(
         &self,
         want: usize,

src/types.rs

@@ -80,13 +80,13 @@ bitflags! {
     /// Options for [`Timeout`](super::Timeout).
     ///
     /// The default behavior is to treat the timespec as a relative time interval. `flags` may
-    /// contain [`types::TimeoutFlags::ABS`] to indicate the timespec represents an absolute
+    /// contain [`TimeoutFlags::ABS`] to indicate the timespec represents an absolute
     /// time. When an absolute time is being specified, the kernel will use its monotonic clock
     /// unless one of the following flags is set (they may not both be set):
-    /// [`types::TimeoutFlags::BOOTTIME`] or [`types::TimeoutFlags::REALTIME`].
+    /// [`TimeoutFlags::BOOTTIME`] or [`TimeoutFlags::REALTIME`].
     ///
     /// The default behavior when the timeout expires is to sever dependent links, as a failed
-    /// request normally would. To keep the links untouched include [`types::TimeoutFlags::ETIME_SUCCESS`].
+    /// request normally would. To keep the links untouched include [`TimeoutFlags::ETIME_SUCCESS`].
     /// CQE will still contain -libc::ETIME in the res field
     #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
     pub struct TimeoutFlags: u32 {
@@ -253,6 +253,9 @@ impl<'prev, 'now> SubmitArgs<'prev, 'now> {
     }
 
     #[inline]
+    /// Signals to mask during waiting for the result
+    ///
+    /// Masked signals will be restored after submit operation returns
     pub fn sigmask<'new>(mut self, sigmask: &'new libc::sigset_t) -> SubmitArgs<'now, 'new> {
         self.args.sigmask = cast_ptr(sigmask) as _;
         self.args.sigmask_sz = std::mem::size_of::<libc::sigset_t>() as _;
@@ -265,6 +268,7 @@ impl<'prev, 'now> SubmitArgs<'prev, 'now> {
     }
 
     #[inline]
+    /// Timeout for submit operation
     pub fn timespec<'new>(mut self, timespec: &'new Timespec) -> SubmitArgs<'now, 'new> {
         self.args.ts = cast_ptr(timespec) as _;