Update Backtrace documentation

[Ayplow]

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.

[shepmaster]

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.

snafu/Cargo.toml

Lines 27 to 41 in 0e18dbd

	[features]
	default = ["std"]
	# Implement the `std::error::Error` trait.
	std = []
	# Makes the backtrace type live
	backtraces = ["std", "backtrace"]
	# The backtrace type becomes `backtrace::Backtrace`
	backtraces-impl-backtrace-crate = ["backtraces"]
	# The backtrace type becomes `std::backtrace::Backtrace` and we
	# implement `std::error::Error::backtrace`
	unstable-backtraces-impl-std = ["backtraces", "snafu-derive/unstable-backtraces-impl-std"]

snafu/src/lib.rs

Lines 94 to 105 in 0e18dbd

	#[cfg(all(
	feature = "backtraces",
	not(feature = "backtraces-impl-backtrace-crate"),
	not(feature = "unstable-backtraces-impl-std"),
	))]
	mod backtrace_shim;
	#[cfg(all(
	feature = "backtraces",
	not(feature = "backtraces-impl-backtrace-crate"),
	not(feature = "unstable-backtraces-impl-std"),
	))]
	pub use crate::backtrace_shim::*;

Without that specified, the "inert" backtrace type is present:

snafu/src/lib.rs

Lines 81 to 92 in 0e18dbd

	#[cfg(all(
	not(feature = "backtraces"),
	not(feature = "backtraces-impl-backtrace-crate"),
	not(feature = "unstable-backtraces-impl-std"),
	))]
	mod backtrace_inert;
	#[cfg(all(
	not(feature = "backtraces"),
	not(feature = "backtraces-impl-backtrace-crate"),
	not(feature = "unstable-backtraces-impl-std"),
	))]
	pub use crate::backtrace_inert::*;

[Ayplow]

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.

[shepmaster]

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.

[shepmaster]

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?

[Plecra]

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.