Document the need to handle the underlying error `source` explicitly

[edmorley]

Hi! Thank you for this crate.

I recently tried migrating one of my projects from fs to fs-err.

Given the README says:

fs-err is a drop-in replacement for std::fs that provides more helpful messages on errors. Extra information includes which operations was attempted and any involved paths.

...and then gives examples like:

failed to open file `does not exist.txt`
    caused by: The system cannot find the file specified. (os error 2)

...I was expecting the error messages to include additional information out of the box, and for their display representation to look like the above.

However, I found that it actually made our project's user-facing error messages worse in many cases (for an example, see https://github.com/heroku/buildpacks-python/issues/270), since the underlying cause is no longer printed, and now only the operation and filename was. Printing the debug representation showed the underlying error existed, but under source.

Searching for the caused by line shown in the README examples, I found it didn't originate in the display representation in fs-err, but instead is a feature of e.g. anyhow: https://github.com/dtolnay/anyhow/blob/afe93e7b167d069ac79f2c7f363b919d3793e6ce/src/fmt.rs#L30

This was surprising, since anyhow isn't mentioned in the README.

I was going to file a bug/feature request about including source in the top-level error's display representation, however, found https://github.com/andrewhickman/fs-err/issues/51 which suggests not including it is by design.

I get the reasoning in that issue (so I'm not necessarily suggesting the fs-err behaviour should be changed), however, this means fs-err isn't quite the drop-in replacement it says it is, and at the very least, I think the README should mention that consumers need to adjust their error logging to print the error source too, if they are not using a library that does it for them (like anyhow).