Check library against Rust API Guidelines

[sunjay]

See: https://rust-lang-nursery.github.io/api-guidelines/checklist.html

In particular, we care about whether the stable public interface of turtle meets these guidelines. Please leave comments about any violations you find and then we'll make a judgement about whether they are severe enough to fix. If you complete checking a given section, please let me know and I will check it off.

Checklist created via: https://euangoddard.github.io/clipboard2markdown/

---

• Naming (crate aligns with Rust naming conventions)
  • [ ] Casing conforms to RFC 430 (C-CASE)
  • [ ] Ad-hoc conversions follow as_, to_, into_ conventions (C-CONV)
  • [ ] Getter names follow Rust convention (C-GETTER)
  • [ ] Methods on collections that produce iterators follow iter, iter_mut, into_iter (C-ITER)
  • [ ] Iterator type names match the methods that produce them (C-ITER-TY)
  • [ ] Feature names are free of placeholder words (C-FEATURE)
  • [ ] Names use a consistent word order (C-WORD-ORDER)
• Interoperability (crate interacts nicely with other library functionality)
  • [ ] Types eagerly implement common traits (C-COMMON-TRAITS)
    • Copy, Clone, Eq, PartialEq, Ord, PartialOrd, Hash, Debug, Display, Default
  • [ ] Conversions use the standard traits From, AsRef, AsMut (C-CONV-TRAITS)
  • [ ] Collections implement FromIterator and Extend (C-COLLECT)
  • [ ] Data structures implement Serde's Serialize, Deserialize (C-SERDE)
  • [ ] Types are Send and Sync where possible (C-SEND-SYNC)
  • [ ] Error types are meaningful and well-behaved (C-GOOD-ERR)
  • [ ] Binary number types provide Hex, Octal, Binary formatting (C-NUM-FMT)
  • [ ] Generic reader/writer functions take R: Read and W: Write by value (C-RW-VALUE)
• Macros (crate presents well-behaved macros)
  • [ ] Input syntax is evocative of the output (C-EVOCATIVE)
  • [ ] Macros compose well with attributes (C-MACRO-ATTR)
  • [ ] Item macros work anywhere that items are allowed (C-ANYWHERE)
  • [ ] Item macros support visibility specifiers (C-MACRO-VIS)
  • [ ] Type fragments are flexible (C-MACRO-TY)
• Documentation (crate is abundantly documented)
  • [ ] Crate level docs are thorough and include examples (C-CRATE-DOC)
  • [ ] All items have a rustdoc example (C-EXAMPLE)
  • [ ] Examples use ?, not try!, not unwrap (C-QUESTION-MARK)
  • [ ] Function docs include error, panic, and safety considerations (C-FAILURE)
  • [ ] Prose contains hyperlinks to relevant things (C-LINK)
  • [ ] Cargo.toml includes all common metadata (C-METADATA)
    • authors, description, license, homepage, documentation, repository, readme, keywords, categories
  • [ ] Crate sets html_root_url attribute "https://docs.rs/CRATE/X.Y.Z" (C-HTML-ROOT)
  • [ ] Release notes document all significant changes (C-RELNOTES)
  • [ ] Rustdoc does not show unhelpful implementation details (C-HIDDEN)
• Predictability (crate enables legible code that acts how it looks)
  • [ ] Smart pointers do not add inherent methods (C-SMART-PTR)
  • [ ] Conversions live on the most specific type involved (C-CONV-SPECIFIC)
  • [ ] Functions with a clear receiver are methods (C-METHOD)
  • [ ] Functions do not take out-parameters (C-NO-OUT)
  • [ ] Operator overloads are unsurprising (C-OVERLOAD)
  • [ ] Only smart pointers implement Deref and DerefMut (C-DEREF)
  • [ ] Constructors are static, inherent methods (C-CTOR)
• Flexibility (crate supports diverse real-world use cases)
  • [ ] Functions expose intermediate results to avoid duplicate work (C-INTERMEDIATE)
  • [ ] Caller decides where to copy and place data (C-CALLER-CONTROL)
  • [ ] Functions minimize assumptions about parameters by using generics (C-GENERIC)
  • [ ] Traits are object-safe if they may be useful as a trait object (C-OBJECT)
• Type safety (crate leverages the type system effectively)
  • [ ] Newtypes provide static distinctions (C-NEWTYPE)
  • [ ] Arguments convey meaning through types, not bool or Option (C-CUSTOM-TYPE)
  • [ ] Types for a set of flags are bitflags, not enums (C-BITFLAG)
  • [ ] Builders enable construction of complex values (C-BUILDER)
• Dependability (crate is unlikely to do the wrong thing)
  • [ ] Functions validate their arguments (C-VALIDATE)
  • [ ] Destructors never fail (C-DTOR-FAIL)
  • [ ] Destructors that may block have alternatives (C-DTOR-BLOCK)
• Debuggability (crate is conducive to easy debugging)
  • [ ] All public types implement Debug (C-DEBUG)
  • [ ] Debug representation is never empty (C-DEBUG-NONEMPTY)
• Future proofing (crate is free to improve without breaking users' code)
  • [ ] Sealed traits protect against downstream implementations (C-SEALED)
  • [ ] Structs have private fields (C-STRUCT-PRIVATE)
  • [ ] Newtypes encapsulate implementation details (C-NEWTYPE-HIDE)
  • [ ] Data structures do not duplicate derived trait bounds (C-STRUCT-BOUNDS)
• Necessities (to whom they matter, they really matter)
  • [ ] Public dependencies of a stable crate are stable (C-STABLE)
  • [ ] Crate and its dependencies have a permissive license (C-PERMISSIVE)

[Ben-PH]

This is a pretty old one. I'd be happy to help with this, but an update and brief mentor instructions would be needed.

[sunjay]

I've updated the checklist with the latest version. As for mentoring instructions, this involves going through the library code and documentation, checking for conformance with each guideline. These are just guidelines, not hard rules, so there may be exceptions that we end up making, but in general we want to aim to conform as much as possible to the items listed.

Thanks for your help!

[Ben-PH]

Rather than go through it by hand only for it to be vulnerable to code rot, I can audit the CI system, making sure that it's picking up each of the points.

...or has that already been done?

[sunjay]

Rather than go through it by hand only for it to be vulnerable to code rot

Yes, this is definitely a valid concern. That's why this issue probably isn't high priority for me until we're closer to 1.0. Having said that, it can still be valuable for someone else to go through the library and check things out. The earlier we catch things, the better.

I can audit the CI system, making sure that it's picking up each of the points.

...or has that already been done?

That has not been done. I don't think the vast majority of these are actually machine checkable. I'm fine with just doing it manually for now. I'll wait to close the issue until the final 1.0 release has been checked. (Still a few months away)

[Ben-PH]

In that case, I'll find something else to check up on. I'll keep this in the back of my mind in the meantime.