docs: add doc comments for error handling on major APIs

[keepsimple1]

This is to fix #463

• Added doc comments about errors in main APIs
• Added a new error variant DaemonShutdown for a specific error.

[rabbit-time]

Looks great! If you think it'd be helpful, I would also suggest adding an example for ServiceDaemon::new that demonstrates a robust use of the API for an application that relies on it.

use std::thread;

let mdns = ServiceDaemon::new().or_else(|err| {
    match err {
        Error::Again => {
            thread::sleep(Duration::from_secs(3));
            ServiceDaemon::new()
        }
        _ => Err(err),
    }
})?;

Maybe something like this? Or perhaps using recursion.

[keepsimple1]

Thanks! I hear you. For ServiceDaemon::new() there is no Error::Again error though. Like in the new docs added, it just returns OS level failures.

As example, currently we have some basic ones in the overall doc usage, and also in example code. Are they helpful, or are you looking for example more specific for error handling?

I updated one line in lib.rs examples to highlight monitor().

[rabbit-time]

Ah, I see. I must have confused it with the browse method when reading through the diff which it might be useful for.

Other than that I think the PR is good how it is now.

[keepsimple1]

Just to clarify, I didn't add example code of handling Error::Again in browse doc comments as it seems not many users in the real world do retry for browse (almost never has the channel full when starting to browse).

It seems some users handle Error::Again around shutdown() or unregister() which kind of makes sense.