Merge pull request #317 from shepmaster/docs

CHANGELOG.md

@@ -4,6 +4,11 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+See the [upgrading guide][] for more detailed information about
+modifying code to account for new releases.
+
+[upgrading guide]: https://docs.rs/snafu/*/snafu/guide/upgrading/index.html
+
 ## [0.7.0] - XXXX-XX-XX
 
 ### Added

src/Snafu.md

@@ -73,11 +73,12 @@ fn main() {
 
 ### Changing the context selector suffix
 
-When context selectors are generated, they have the suffix `Snafu`
-added by default. If you'd prefer a different suffix, such as `Ctx` or
-`Context`, you can specify that with
-`#[snafu(context(suffix(SomeIdentifier)))]`. If you'd like to disable
-the suffix entirely, you can use `#[snafu(context(suffix(false)))]`.
+When context selectors are generated, any `Error` suffix is removed
+and the suffix `Snafu` is added by default. If you'd prefer a
+different suffix, such as `Ctx` or `Context`, you can specify that
+with `#[snafu(context(suffix(SomeIdentifier)))]`. If you'd like to
+disable the suffix entirely, you can use
+`#[snafu(context(suffix(false)))]`.
 
 **Example**
 
@@ -86,7 +87,7 @@ the suffix entirely, you can use `#[snafu(context(suffix(false)))]`.
 #
 #[derive(Debug, Snafu)]
 enum Error {
-    UsesTheDefaultSuffix,
+    UsesTheDefaultSuffixError,
 
     #[snafu(context(suffix(Ctx)))]
     HasAnotherSuffix,

src/guide/upgrading.md

@@ -9,6 +9,12 @@
 
 ## Version 0.6 → 0.7
 
+Upgrading should be a tedious but straightforward process. To assist
+upgrading your code, you can use the [snafu-upgrade-assistant], which
+attempts to automatically update breaking changes.
+
+[snafu-upgrade-assistant]: https://github.com/shepmaster/snafu-upgrade-assistant
+
 ### Context selector names have changed
 
 Previously, context selector names for enum errors exactly matched
@@ -17,13 +23,55 @@ confusion for people new to SNAFU. It was also inconsistent with
 context selector names for struct errors.
 
 Now, context selectors for both enum and struct errors use the `Snafu`
-suffix.
+suffix. Any existing `Error` suffix is removed before `Snafu` is
+added.
 
-Upgrading should be a tedious but straightforward process. To assist
-upgrading your code, you can use the [snafu-upgrade-assistant], which
-attempts to locate all of your context selectors and rename them.
+#### Before
 
-[snafu-upgrade-assistant]: https://github.com/shepmaster/snafu-upgrade-assistant
+```rust,ignore
+#[derive(Debug, Snafu)]
+struct StructError;
+
+#[derive(Debug, Snafu)]
+enum EnumError {
+    VariantError,
+}
+
+ensure!(false, StructContext);
+ensure!(false, VariantError);
+```
+
+#### After
+
+```rust,ignore
+#[derive(Debug, Snafu)]
+struct StructError;
+
+#[derive(Debug, Snafu)]
+enum EnumError {
+    VariantError,
+}
+
+ensure!(false, StructSnafu);
+ensure!(false, VariantSnafu);
+```
+
+### `with_context` takes an argument
+
+`ResultExt::with_context`, `TryFutureExt::with_context`, and
+`TryStreamExt::with_context` now pass the error into the closure.
+
+#### Before
+
+```rust,ignore
+some_result.with_context(|| ContextSelector);
+```
+
+#### After
+
+```rust,ignore
+some_result.with_context(|_| ContextSelector);
+```
 
 ### String attribute parsing is no longer supported
 
@@ -75,7 +123,7 @@ The `backtrace-crate` feature flag has been renamed to
 `backtraces-impl-backtrace-crate`. The backtrace returned by
 `ErrorCompat::backtrace` is now the `backtrace::Backtrace` type when
 this flag is enabled, so the implementation of `AsRef` has been
-removed..
+removed.
 
 ### Futures
 

src/lib.rs

@@ -20,7 +20,7 @@
 #![cfg_attr(feature = "futures", doc = "   - [`Futures`](futures::TryFutureExt)")]
 #![cfg_attr(feature = "futures", doc = "   - [`Streams`](futures::TryStreamExt)")]
 //! - Suitable for libraries and applications
-//! - `no-std` compatibility
+//! - `no_std` compatibility
 //! - Generic types and lifetimes
 //!
 //! For detailed information, please see the [user's guide](guide).
@@ -76,7 +76,7 @@
 //! that occurs, it's time to create your own error type by deriving
 //! [`Snafu`][]!
 //!
-//! ### Structs
+//! ### Struct style
 //!
 //! SNAFU will read your error struct definition and create a *context
 //! selector* type (called `InvalidIdSnafu` in this example). These
@@ -117,7 +117,7 @@
 //! }
 //! ```
 //!
-//! ### Enums
+//! ### Enum style
 //!
 //! While error structs are good for constrained cases, they don't
 //! allow for reporting multiple possible kinds of errors at one