search

shepmaster / snafu

Easily assign underlying errors into domain-specific errors while adding context
https://docs.rs/snafu/
Apache License 2.0
1.45k stars 61 forks source link

Confusion in docs about if backtrace feature is enabled by default #197

Open scrabsha opened 4 years ago

scrabsha commented 4 years ago

Hello, There are two information about the default state of the backtrace feature.

As such, one of these two pages is wrong. I am no expert in how features are declared in Cargo.toml, but I think the default behaviour is backtrace disabled by default.

If this issue is accepted, then I'll be very happy to provide you a PR to fix the documentation.

shepmaster commented 4 years ago

snafu::Backtrace page says it is enabled by default,

It does not say that; it actually says (emphasis mine)

Backtrace functionality is currently enabled.

“Currently” does not mean “default“. Could you suggest another wording that would be more understandable?

scrabsha commented 4 years ago

Wow sorry, I though the documentation system in cargo is static and is always the same, no matter the features selected. Generating custom documentation according to feature flags is a very nice idea!

This confused me because I was reading online documentation, so "currently" had no sense to me.

Unfortunately, my english level is not that high, so the best way to me to say it would be:

This documentation was compiled with Backtrace functionality enabled.

This is a way heavier style, but that's the best idea I have. It would allow someone with low experience, reading online, not to make my mistake.

However, I don't think my suggestion worth the cost: as you pointed out, it was a misunderstanding from my part and not a confusion from the documentation.

shepmaster commented 4 years ago

It's worth pointing out that we enable non-default features on docs.rs