Format, fix, document, Etc 07/15

[rarensu]

Improved documentation for many items. Update: removed unused Result type. Update: properly using the Result type, where appropriate, while avoiding some avoidable panics.

Previous PR in sequence was #400
Next PR in sequence was #402

An additional PR #405 branches from this point.

[cberner]

Had a minor comment about non-errors which I don't think we should document. If it doesn't make sense for a function to return an error, we should change the signature instead

[rarensu]

I removed the redundant "does not error" documentation. Instead, I propose a commit in which we remove the unused Result type.

Update: Sorry about the repeated pushing. Cargo fmt was being picky and rebasing is tricky sometimes.

[rarensu]

@cberner
About returning a meaningful error in BackgroundSession::new(). Since the error type has to match the error type of the mount/spawn functions I had to convert from poison error to io error. It's not great, but it's better than having a # Panic section. Sadly, this addition triggered cargo fmt to insist on breaking up the method chain.

About the unmount functions. Claude suggested that it makes sense to handle the error, rather than return it, for the unmount case. Just because another thread panicked, doesn't mean that an unmount is unsafe or impossible. In fact, probably, the mount data is just fine and we can still do the unmount. No panics, no errors, it just does what it does.

[cberner]

Hmm, I'll need to look at that change some more. Can you split the panic changes into a separate PR? Let's make this one only about the doc changes

[cberner]

Let's remove this. It's an implementation detail

[rarensu]

Clippy says if the function can panic, it should have documentation about that. Are you saying that we should pretend that the function cannot panic?

[cberner]

I think we should only document things that are part of the public API, rather than implementation details. That is they're not going to change

[rarensu]

I removed most of them, but I didn't remove this one. Joining a background thread can panic, and sometimes should, panic. For example,

• A panic in the session thread would propagate to the main thread on join().
• A deadlocked session thread may or may not cause a panic on join(), depending on the OS.

These are both just a normal part of joining a background thread. The underlying call to thread::join() even has its own # Panic documentation. It would be disingenuous to imply that our function is somehow free from panics.

I did improve the # Panic section by clarifying an example.

[cberner]

Propagates errors due to communicating with the fuse device.

Let's remove this in all the messages. I don't think it adds useful information. Returning an io::Result already explains that it propagates errors

[rarensu]

I guess that is a fair criticism.

[rarensu]

Reverted all of the unnecessary ones, but I did need to write something for the notify functions, so I revised the statement to clarify that it's the kernel causing the errors.

[cberner]

Merged. Thanks for iterating on this. lgtm!