snafu
snafu copied to clipboard
shepmaster
Update Backtrace documentation
The guide has the backtraces feature listed as disabled, and it seems the inline documentation fell out of date. Just it case, it'd be a good idea to review similar places in the documentation.
Either that, or find a way to verify it? Maybe a doctest could force the explanation to keep up to date.
I think this is a misunderstanding. The module you edited is the backtrace shim, which provides a newtype wrapper around the backtrace crate. When that module is enabled (via backtraces), then backtrace collection is enabled.
https://github.com/shepmaster/snafu/blob/0e18dbd730fcb0b6c207e0ae29246e32387d362d/Cargo.toml#L27-L41
https://github.com/shepmaster/snafu/blob/0e18dbd730fcb0b6c207e0ae29246e32387d362d/src/lib.rs#L94-L105
Without that specified, the "inert" backtrace type is present:
https://github.com/shepmaster/snafu/blob/0e18dbd730fcb0b6c207e0ae29246e32387d362d/src/lib.rs#L81-L92
Ah I see, then this might not be the best way to improve the documentation. I found the source file through https://docs.rs/snafu/0.6.2/snafu/struct.Backtrace.html which seems to use the shim for its' source. As that isn't the default feature set, it wasn't clear how I was meant to enable the struct.
I found the source file through docs.rs
Yes, on docs.rs we enable the backtrace feature by default (among other things) so that the documentation that most users will browse shows more of the features available.
See also #197. Obviously this is a problem as multiple people have been confused about it, but I'm not sure how to solve the problem.
The only thing that comes to mind copy-pasting a paragraph about how Cargo has features and how docs.rs has a different set of features from the default into the docs of every function that makes use of feature flags.
Thoughts?
The features only change the behavior of the Backtrace struct, right? I think just using the same documentation between the different implementations should be enough. It'd sidestep the problem of choosing the feature set to compile the docs with too.
