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

Document context selectors and mention semver breakage when exporting them #171

Closed Robzz closed 5 years ago

Robzz commented 5 years ago

This PR generates some default documentation for SNAFU context selector types and adds a mention of possible semver breakage in the user guide, in the section discussing the visibility attribute.

I'm opening this already, so that we can discuss and improve the wording of the documentation enhancements if needed. I'll deal with generating the documentation when I have the time to dive into snafu-derive, hopefully later this week.

Closes #168
Closes #170

shepmaster commented 5 years ago

[WIP]

FYI, GitHub has draft pull requests now.

Robzz commented 5 years ago

FYI, GitHub has draft pull requests now.

Didn't know that, thanks!

I just added the selectors documentation. As predicted, I also had to document the selector fields, but I couldn't think of a helpful default documentation so I just added #allow[missing_docs] to those. I also had to document the fail method that's generated for some selectors.

Let me know if you'd like any changes.

Robzz commented 5 years ago

Apparently the CI was unhappy about the formatting, I ran rustfmt and it now passes on rust stable. It still fails on rust 1.18 and 1.30 but it looks unrelated to this PR.

shepmaster commented 5 years ago

It still fails on rust 1.18 and 1.30

We are actually right in the middle of some reorganizing and breaking changes, so I rebased you on master where we now support only Rust 1.31+. I made some small tweaks to the language and added a test to ensure that the docs are generated. I force-pushed all that to your branch.

Let me know if the changes look good to you!

Robzz commented 5 years ago

It still builds with my usecase so yeah, all good!