Format, fix, document, Etc 07/15

src/lib.rs

@@ -183,7 +183,9 @@ impl KernelConfig {
     ///
     /// The kernel currently has a hard maximum value of 2.  Anything higher won't work.
     ///
-    /// On success, returns the previous value.  On error, returns the nearest value which will succeed.
+    /// On success, returns the previous value.  
+    /// # Errors
+    /// If argument is too large, returns the nearest value which will succeed.
     #[cfg(feature = "abi-7-40")]
     pub fn set_max_stack_depth(&mut self, value: u32) -> Result<u32, u32> {
         // https://lore.kernel.org/linux-fsdevel/CAOYeF9V_n93OEF_uf0Gwtd=+da0ReX8N2aaT6RfEJ9DPvs8O2w@mail.gmail.com/
@@ -202,7 +204,9 @@ impl KernelConfig {
     ///
     /// Must be a power of 10 nanoseconds. i.e. 1s, 0.1s, 0.01s, 1ms, 0.1ms...etc
     ///
-    /// On success returns the previous value. On error returns the nearest value which will succeed
+    /// On success returns the previous value.  
+    /// # Errors
+    /// If the argument does not match any valid granularity, returns the nearest value which will succeed.
     #[cfg(feature = "abi-7-23")]
     pub fn set_time_granularity(&mut self, value: Duration) -> Result<Duration, Duration> {
         if value.as_nanos() == 0 {
@@ -226,7 +230,9 @@ impl KernelConfig {
 
     /// Set the maximum write size for a single request
     ///
-    /// On success returns the previous value. On error returns the nearest value which will succeed
+    /// On success returns the previous value.
+    /// # Errors
+    /// If the argument is too large, returns the nearest value which will succeed.
     pub fn set_max_write(&mut self, value: u32) -> Result<u32, u32> {
         if value == 0 {
             return Err(1);
@@ -241,7 +247,9 @@ impl KernelConfig {
 
     /// Set the maximum readahead size
     ///
-    /// On success returns the previous value. On error returns the nearest value which will succeed
+    /// On success returns the previous value.
+    /// # Errors
+    /// If the argument is too large, returns the nearest value which will succeed.
     pub fn set_max_readahead(&mut self, value: u32) -> Result<u32, u32> {
         if value == 0 {
             return Err(1);
@@ -256,7 +264,8 @@ impl KernelConfig {
 
     /// Add a set of capabilities.
     ///
-    /// On success returns Ok, else return bits of capabilities not supported when capabilities you provided are not all supported by kernel.
+    /// # Errors
+    /// When the argument includes capabilities not supported by the kernel, returns the bits of the capabilities not supported.
     pub fn add_capabilities(&mut self, capabilities_to_add: u64) -> Result<(), u64> {
         if capabilities_to_add & self.capabilities != capabilities_to_add {
             return Err(capabilities_to_add - (capabilities_to_add & self.capabilities));
@@ -267,7 +276,9 @@ impl KernelConfig {
 
     /// Set the maximum number of pending background requests. Such as readahead requests.
     ///
-    /// On success returns the previous value. On error returns the nearest value which will succeed
+    /// On success returns the previous value.
+    /// # Errors
+    /// If the argument is too small, returns the nearest value which will succeed.
     pub fn set_max_background(&mut self, value: u16) -> Result<u16, u16> {
         if value == 0 {
             return Err(1);
@@ -280,7 +291,9 @@ impl KernelConfig {
     /// Set the threshold of background requests at which the kernel will consider the filesystem
     /// request queue congested. (it may then switch to sleeping instead of spin-waiting, for example)
     ///
-    /// On success returns the previous value. On error returns the nearest value which will succeed
+    /// On success returns the previous value.
+    /// # Errors
+    /// If the argument is too small, returns the nearest value which will succeed.
     pub fn set_congestion_threshold(&mut self, value: u16) -> Result<u16, u16> {
         if value == 0 {
             return Err(1);
@@ -952,6 +965,9 @@ pub trait Filesystem {
 /// not return until the filesystem is unmounted.
 ///
 /// Note that you need to lead each option with a separate `"-o"` string.
+/// # Errors
+/// Returns an error if the options are incorrect, or if the fuse device can't be mounted,
+/// and any final error when the session comes to an end.
 #[deprecated(note = "use mount2() instead")]
 pub fn mount<FS: Filesystem, P: AsRef<Path>>(
     filesystem: FS,
@@ -966,6 +982,9 @@ pub fn mount<FS: Filesystem, P: AsRef<Path>>(
 /// not return until the filesystem is unmounted.
 ///
 /// NOTE: This will eventually replace `mount()`, once the API is stable
+/// # Errors
+/// Returns an error if the options are incorrect, or if the fuse device can't be mounted,
+/// and any final error when the session comes to an end.
 pub fn mount2<FS: Filesystem, P: AsRef<Path>>(
     filesystem: FS,
     mountpoint: P,
@@ -980,6 +999,8 @@ pub fn mount2<FS: Filesystem, P: AsRef<Path>>(
 /// and therefore returns immediately. The returned handle should be stored
 /// to reference the mounted filesystem. If it's dropped, the filesystem will
 /// be unmounted.
+/// # Errors
+/// Returns an error if the options are incorrect, or if the fuse device can't be mounted.
 #[deprecated(note = "use spawn_mount2() instead")]
 pub fn spawn_mount<'a, FS: Filesystem + Send + 'static + 'a, P: AsRef<Path>>(
     filesystem: FS,
@@ -1002,6 +1023,8 @@ pub fn spawn_mount<'a, FS: Filesystem + Send + 'static + 'a, P: AsRef<Path>>(
 /// be unmounted.
 ///
 /// NOTE: This is the corresponding function to mount2.
+/// # Errors
+/// Returns an error if the options are incorrect, or if the fuse device can't be mounted.
 pub fn spawn_mount2<'a, FS: Filesystem + Send + 'static + 'a, P: AsRef<Path>>(
     filesystem: FS,
     mountpoint: P,

src/ll/reply.rs

@@ -407,7 +407,7 @@ impl<T: AsRef<Path>> DirEntry<T> {
     }
 }
 
-/// Used to respond to [ReadDirPlus] requests.
+/// Data buffer used to respond to [`Readdir`] requests.
 #[derive(Debug)]
 pub struct DirEntList(EntListBuf);
 impl From<DirEntList> for Response<'_> {
@@ -471,7 +471,7 @@ impl<T: AsRef<Path>> DirEntryPlus<T> {
     }
 }
 
-/// Used to respond to [ReadDir] requests.
+/// Data buffer used to respond to [`ReaddirPlus`] requests.
 #[derive(Debug)]
 pub struct DirEntPlusList(EntListBuf);
 impl From<DirEntPlusList> for Response<'_> {

src/notify.rs

@@ -30,6 +30,8 @@ impl PollHandle {
     }
 
     /// Notify the kernel that the associated file handle is ready to be polled.
+    /// # Errors
+    /// Returns an error if the kernel rejects the notification.
     pub fn notify(self) -> io::Result<()> {
         self.notifier.poll(self.handle)
     }
@@ -57,25 +59,35 @@ impl Notifier {
     }
 
     /// Notify poll clients of I/O readiness
+    /// # Errors
+    /// Returns an error if the kernel rejects the notification.
     pub fn poll(&self, kh: u64) -> io::Result<()> {
         let notif = Notification::new_poll(kh);
         self.send(notify_code::FUSE_POLL, &notif)
     }
 
     /// Invalidate the kernel cache for a given directory entry
+    /// # Errors
+    /// Returns an error if the notification data is too large.
+    /// Returns an error if the kernel rejects the notification.
     pub fn inval_entry(&self, parent: u64, name: &OsStr) -> io::Result<()> {
         let notif = Notification::new_inval_entry(parent, name).map_err(Self::too_big_err)?;
         self.send_inval(notify_code::FUSE_NOTIFY_INVAL_ENTRY, &notif)
     }
 
     /// Invalidate the kernel cache for a given inode (metadata and
     /// data in the given range)
+    /// # Errors
+    /// Returns an error if the kernel rejects the notification.
     pub fn inval_inode(&self, ino: u64, offset: i64, len: i64) -> io::Result<()> {
         let notif = Notification::new_inval_inode(ino, offset, len);
         self.send_inval(notify_code::FUSE_NOTIFY_INVAL_INODE, &notif)
     }
 
     /// Update the kernel's cached copy of a given inode's data
+    /// # Errors
+    /// Returns an error if the notification data is too large.
+    /// Returns an error if the kernel rejects the notification.
     pub fn store(&self, ino: u64, offset: u64, data: &[u8]) -> io::Result<()> {
         let notif = Notification::new_store(ino, offset, data).map_err(Self::too_big_err)?;
         // Not strictly an invalidate, but the inode we're operating
@@ -85,6 +97,9 @@ impl Notifier {
 
     /// Invalidate the kernel cache for a given directory entry and inform
     /// inotify watchers of a file deletion.
+    /// # Errors
+    /// Returns an error if the notification data is too large.
+    /// Returns an error if the kernel rejects the notification.
     pub fn delete(&self, parent: u64, child: u64, name: &OsStr) -> io::Result<()> {
         let notif = Notification::new_delete(parent, child, name).map_err(Self::too_big_err)?;
         self.send_inval(notify_code::FUSE_NOTIFY_DELETE, &notif)

src/reply.rs

@@ -276,6 +276,8 @@ impl Reply for ReplyOpen {
 
 impl ReplyOpen {
     /// Reply to a request with the given open result
+    /// # Panics
+    /// When attempting to use kernel passthrough. Use `opened_passthrough()` instead.
     pub fn opened(self, fh: u64, flags: u32) {
         #[cfg(feature = "abi-7-40")]
         assert_eq!(flags & FOPEN_PASSTHROUGH, 0);
@@ -326,7 +328,7 @@ impl Reply for ReplyWrite {
 }
 
 impl ReplyWrite {
-    /// Reply to a request with the given open result
+    /// Reply to a request with the number of bytes written
     pub fn written(self, size: u32) {
         self.reply.send_ll(&ll::Response::new_write(size));
     }
@@ -354,7 +356,7 @@ impl Reply for ReplyStatfs {
 }
 
 impl ReplyStatfs {
-    /// Reply to a request with the given open result
+    /// Reply to a statfs request with filesystem information
     #[allow(clippy::too_many_arguments)]
     pub fn statfs(
         self,
@@ -395,7 +397,9 @@ impl Reply for ReplyCreate {
 }
 
 impl ReplyCreate {
-    /// Reply to a request with the given entry
+    /// Reply to a request with a newly created file entry and its newly open file handle
+    /// # Panics
+    /// When attempting to use kernel passthrough. Use `opened_passthrough()` instead.
     pub fn created(self, ttl: &Duration, attr: &FileAttr, generation: u64, fh: u64, flags: u32) {
         #[cfg(feature = "abi-7-40")]
         assert_eq!(flags & FOPEN_PASSTHROUGH, 0);
@@ -432,7 +436,7 @@ impl Reply for ReplyLock {
 }
 
 impl ReplyLock {
-    /// Reply to a request with the given open result
+    /// Reply to a request with a file lock
     pub fn locked(self, start: u64, end: u64, typ: i32, pid: u32) {
         self.reply.send_ll(&ll::Response::new_lock(&ll::Lock {
             range: (start, end),
@@ -464,7 +468,7 @@ impl Reply for ReplyBmap {
 }
 
 impl ReplyBmap {
-    /// Reply to a request with the given open result
+    /// Reply to a request with a bmap
     pub fn bmap(self, block: u64) {
         self.reply.send_ll(&ll::Response::new_bmap(block));
     }
@@ -492,7 +496,7 @@ impl Reply for ReplyIoctl {
 }
 
 impl ReplyIoctl {
-    /// Reply to a request with the given open result
+    /// Reply to a request with an ioctl
     pub fn ioctl(self, result: i32, data: &[u8]) {
         self.reply
             .send_ll(&ll::Response::new_ioctl(result, &[IoSlice::new(data)]));
@@ -521,7 +525,7 @@ impl Reply for ReplyPoll {
 }
 
 impl ReplyPoll {
-    /// Reply to a request with the given poll result
+    /// Reply to a request with ready poll events
     pub fn poll(self, revents: u32) {
         self.reply.send_ll(&ll::Response::new_poll(revents));
     }
@@ -645,12 +649,12 @@ impl Reply for ReplyXattr {
 }
 
 impl ReplyXattr {
-    /// Reply to a request with the size of the xattr.
+    /// Reply to a request with the size of an extended attribute
     pub fn size(self, size: u32) {
         self.reply.send_ll(&ll::Response::new_xattr_size(size));
     }
 
-    /// Reply to a request with the data in the xattr.
+    /// Reply to a request with the data of an extended attribute
     pub fn data(self, data: &[u8]) {
         self.reply.send_ll(&ll::Response::new_slice(data));
     }

src/session.rs

@@ -75,6 +75,8 @@ impl<FS: Filesystem> AsFd for Session<FS> {
 
 impl<FS: Filesystem> Session<FS> {
     /// Create a new session by mounting the given filesystem to the given mountpoint
+    /// # Errors
+    /// Returns an error if the options are incorrect, or if the fuse device can't be mounted.
     pub fn new<P: AsRef<Path>>(
         filesystem: FS,
         mountpoint: P,
@@ -142,6 +144,8 @@ impl<FS: Filesystem> Session<FS> {
     /// calls into the filesystem. This read-dispatch-loop is non-concurrent to prevent
     /// having multiple buffers (which take up much memory), but the filesystem methods
     /// may run concurrent by spawning threads.
+    /// # Errors
+    /// Returns any final error when the session comes to an end.
     pub fn run(&mut self) -> io::Result<()> {
         // Buffer for receiving requests from the kernel. Only one is allocated and
         // it is reused immediately after dispatching to conserve memory and allocations.
@@ -262,6 +266,8 @@ impl BackgroundSession {
         })
     }
     /// Unmount the filesystem and join the background thread.
+    /// # Panics
+    /// Panics if the background thread can't be recovered (e.g., because it panicked).
     pub fn join(self) {
         let Self {
             guard,