New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Misleading backtrace documentation on docs.rs #332
Comments
It is enabled on docs.rs though. Line 25 in 6159ea9
What do you propose as an alternate? |
I think the tokio docs make it pretty clear that a feature is needed. A bit of digging showed that they use #[cfg(doc)] together with #[cfg(docsrs)]. I tried to prototype this here for snafu. You need to build that branch with I find it a bit ugly to be honest, but it makes it much more clear. A lighter alternative would be just use |
Respectfully, how much advantage comes from using conditional compilation at all rather than a static statement that "This functionality is available only if the Cargo feature |
SNAFU's use of features with respect to To that end, the
Those last two are mutually exclusive — a type alias can only point to one concrete type 😉. This is another reason that those feature flags should only be chosen by the binary. In a world where the standard library has stabilized a Circling back to the |
My point is just that I confused the message on docs.rs "Backtrace functionality is currently enabled." with "The backtraces feature is enabled by default". I think we can do the most precise phrasing using #[cfg]. However a static phrasing might works as well, such as
But that is a bit weird I must say :) |
This line:
snafu/src/backtrace_shim.rs
Line 6 in 6159ea9
Gets rendered into docs.rs here:
https://docs.rs/snafu/latest/snafu/struct.Backtrace.html
Which made me think that I don't need to enable the feature
backtraces
to actually get backtraces. Cost me a few minutes to figure this out :)I think we should make it more clear that Backtraces are only available if the
backtraces
feature is enabled.The text was updated successfully, but these errors were encountered: