Crate evaluation for 2017-06-27: error-chain
For additional contribution opportunities, see the main libz blitz thread.
This post is a wiki. Feel free to edit it.
Needs your help!
Anything that is not checked off still needs your help! There is no need to sign up or ask for permission - follow any of these links and leave your thoughts:
[y]= guideline is adhered to, no work needed.
[n]= guideline may need work, see comments nearby
[/]= guideline not applicable to this crate
This document is collaboratively editable. Pick a few of the guidelines, compare the
error-chain crate against them, and fill in the checklist with
[y] if the crate conforms to the guideline,
[n] if the crate does not conform, and
[/] if the guideline does not apply to this crate. Each guideline is explained in more detail here. If
[n], please add a brief note on the following line with an explanation. For example:
- [n] Crate name is a palindrome (C-PALINDROME) - error-chain backwards is niahc-rorre which is not the same as error-chain
Cookbook use case statements
Come up with ideas for nice introductory examples of using
error-chain, possibly in combination with other crates, that would be good to show in the Rust Cookbook. Please leave a comment in that issue with your ideas! You don’t necessarily have to write the example code yourself but PRs are always welcome.
API guideline updates
What lessons can we learn from
error-chain that will be broadly applicable to other crates? Please leave a comment in that issue with your ideas!
- What do guidelines say about hidden macro conventions?
How to support no_std.
Suitability for libraries
- error-chain is definitely oriented towards getting started quickly writing apps, but it isn’t obviously wrong for libs to use error-chain. Should it be explicitly recommended either way?
Design compromises around links / foreign links
When and how to enable backtraces
- This has been iterated on a lot and has performance implications
Structural typing between ‘links’ in from conversions
- some interop implications here
- What is the purpose of
ChainedErrorbeing a trait?
extract_backtracemake sense as a method on the
ChainedErrortrait? It doesn’t use the trait in any way
- Why the
ChainedErrorbe hidden or made private?
- What is the purpose of
There are several issues around the macro syntax:
- The syntax not matching corresponding declaration form
- The types declaration, with its hand-rolled system of defaults, doesn’t quite feel “rustic”
- Attributes only coming after items
- No ability to place attributes or visibility modifiers on
- No ability to use generics in error variants
- Cannot document fields in struct type error
- Cannot currently use
deriveon the Error type
- Links with custom description/display
There’s not currently a good story for boxing up chainable errors
The names “links” and “foreign links” are not fully evocative of the crucial distinction: whether chaining occurs
- It’d be good to dive more deeply into the rationale for this precise split.
- (brson) links allow for deep matching on chained error types and backtrace-propagation
because they follow the error-chain ‘protocol’. Their
Fromconversions pass the backtrace between each other, while building up a nested enum for the ErrorKind.
- (brson) foreign_links do not follow the error-chain protocol and can do neither of these things
What are the pros/cons of locally defining
- It seems like
linkscould be simplified if
Errors were just type aliases
- (brson) I doubt it is possible to formulate it in such a way because of coherence issues. I did try. The ResultExt trait that defines chain_err is defined in terms of the local ErrorKind. The inability to define a single ChainedError type and need to define so many local types is pretty much the reason the error-chain crate is one massive macro.
- It seems like
ErrorKind, how do we feel about that?
- (brson) seems like an abuse of Deref
Msg(String)always being a variant, with conversions – worth talking about
- This may be one aspect that separates libs from apps
quick_error– can these be hidden?
- (brson) not
- (brson) istm everything but error_chain and quick_main should be hidden and follow some convention for hidden macros
- (brson) not
Do we want to allow conversions with
- (brson) I think it should be required, and that non-Send/Sync Errors are non-interoperable special cases, need to think hard about their choices.
Eliminate duplication in quick_run! handling
The crate doc has a few inconsistencies
- The example usage doesn’t match the included sample generated code
- Broken links on docs.rs: https://docs.rs/error-chain/0.10.0/error_chain/example_generated (adding index.html works)
- Section on foreign links references a prior example that doesn’t seem to exist
Rename and hide the quick_error macro
quick_error!provides syntax that
error_chain!doesn’t actually use
- can this be rewritten for error_chain’s exact syntax?
How are we tracking?
Do these before the libs team review.
- [x] Create evaluation thread based on this template
- [x] Work with author and issue tracker to identify known blockers
- [x] Compare crate to guidelines by filling in checklist
- [x] Record other questions and notes about crate
- [ ] Draft several use case statements to serve as cookbook examples
- [ ] Record recommendations for updated guidelines
Do these after the libs team review.
- [ ] Publish libs team meeting video
- [ ] Create new issues and tracking issue on crate’s issue tracker
- [ ] Solicit use cases for cookbook examples related to the crate
- [ ] File issues to implement cookbook examples
- [ ] File issues to update guidelines
- [ ] Post all approachable issues to TWiR call for participation thread
- [ ] Update links in coordination thread