Crate evaluation for 2017-06-13: walkdir
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
walkdir 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) - walkdir backwards is ridklaw which is not the same as walkdir
Cookbook use case statements
Come up with ideas for nice introductory examples of using
walkdir, 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
walkdir that will be broadly applicable to other crates? Please leave a comment in that issue with your ideas!
walkdir is already stable, so we should try find non-breaking solutions, but @burntsushi isn’t against a
2.0 release if there’s enough in it.
Links to types in
There are a lot of references to types in
std::fs. Should these be links to the relevant section in the
std API docs? If so, where should they point?
stdreferences to https://doc.rust-lang.org/stable/std/
- Ping @steveklabnik about the
stddocs. Will this change?
Custom iterator adapters
WalkDirIterator::filter_entry is not obviously better than
filter_entry behaves differently to
filter in a way that isn’t clear from the function signatures.
Are there expectations on what an Iterator adapter should look like?
- Predicate input as
- Chainable with any other adapter:
filter_entryis only available on
Could we solve this with a new name/docs/examples:
- Maybe rename to
filter_walk? It might be helpful to think of it as a driver for the walk that always comes before
filter, operating on an already determined set of entries
- Example for use-cases that exploit the file structure (and may want to
- Example for use-cases that ignore the file structure (and wouldn’t want to
filter_entry a method on
WalkDir instead of an adapter?
WalkDirIteratormethods inherent on
WalkDirIteratortrait in favour of inherent methods
- Add doc example for
filterwhy choose one over the other
WalkDirIterator be externally implementable?
WalkDirIterator is implemented by a few types internally, but doesn’t seem to have any value being implemented externally. Should it have a
Sealed supertype to signal that it’s not for implementing?
- Irrelevant since we’re removing the trait
Determining send/sync still hard.
WalkDirOptions is not
Send, which prevents
Iter from being
Send. Maybe we could create
assert_sync! macros and apply them to every type.
Should we strengthen recommendation to assert types are send/sync by default?
Send + Sync
assert_syncmacros and test:
@KodrAus to open a Pre-RFC about asserting
Error conditions for iterators returning results
Iter::next's Error conditions be documented if
Iter::Item is a
Result? On the impl of next? On the iterator itself?
- Add Errors section to
- @KodrAus to file guideline issue about Error sections for trait methods returning errors
- @KodrAus to file issue about rust-doc calling out overridden trait docs more
unwrap on a
Vec that’s guaranteed not to panic by the block it’s in. Should this be
expect with a comment describing why it can’t fail?
Could any of these be refactored to avoid the
unwrap altogether? All methods calling
unwrap that are validated:
<Iter as Iterator>::next
Should there be a guideline for this?
expectand document why they won’t panic
- Open guidelines issue about
is_same_file function be re-exported from the unstable
same_file crate? It isn’t mentioned in docs or used in examples. Looks like it was pulled into a new crate post
1.0 and re-exported to prevent a breaking change.
- Deprecate re-export in favour of
- Remove re-export in
sorter support more metadata to compare like size, last modified? It should at least use
OsStr instead of
- Open issue to support sorting by more file metadata (might not be feasible)
- At least change
Raised during the meeting that
DirEntry::ino is a unix only method, but that isn’t reflected in the docs.
unix::DirEntryExttrait and add
- Remove inherent
- Document that
DirEntryExtis unix only
[details=Summary]- Add Error documentation sections for
Iter::next- probably should be documented in both places? See discussion
- docs: Indicate that DirEntry::ino is Unix only
- docs: remove unwrap from
- examples in root
- examples on
- examples on
- docs: clarify differences between
- add examples for
- demonstrate differences with
std::fs::DirEntryin method examples
- add examples for
- docs: add example for
- docs: add links for:
filter_entryin root skip hidden files and directories efficiently on unix example
- docs: Add a note that
IterFilterEntryis created by calling
- docs: Correct inaccuracies in
WalkDirroot docs: if
truethen directories aren’t emitted before their contents. The order isn’t unspecified if a
sort_bypredicate is given
- Add Debug to Iter, IterFilterEntry, WalkDir
- Add CI for OSX (?) and crate badges for tier 1 platforms
- Add categories metadata to Cargo.toml
Evaluation task assignments
- [ ] @KodrAus
- [ ] @KodrAus follow up stability of
- [ ] @KodrAus follow up rustdoc calling out overridden trait method docs
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
- [x] Draft several use case statements to serve as cookbook examples
- [x] Record recommendations for updated guidelines
Do these after the libs team review.
- [x] Publish libs team meeting video
- [x] 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