Make the crate conform to the API guidelines

[tcharding]

Rust API Guidelines Checklist

• 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,
      keywords, categories
  • 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)
  (Both done in Make a start on verifying the API #136)
  • 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)

[tcharding]

The only public dependency is serde and it is stable. arrayvec is unstable but is private. C-STABLE is done.

[tcharding]

Both sered and arrayvec use MIT or Apache 2.0, this crate uses CC0-1.0. C-PERMISSIVE is done.

[tcharding]

Done in #136:

• C-DEBUG
• C-DEBUG-NONEMPTY
• C-COMMON-TRAITS
• C-SEND-SYNC
• C-GOOD-ERR

[tcharding]

Type Safety section:

• C-NEWTYPE and C-CUSTOM-TYPE: Manually checked function parameters using gg 'pub fn'
• C-BITFLAG: There is only a single enum Case, it does not need to be a bitflag
• C-BUILDER: There are no complex data structures in the hex crate

[tcharding]

Future Profing section:

• C-SEALED: There are two public traits that are meant to be implemented downstream (FromHex and DisplayHex) and one already sealed trait (IsRef).
• C-STRUCT-PRIVATE: All structs have private fields except the serde ones which are public by design (see also Audit serde module #137)
• C-NEWTYPE-HIDE: Manually checked public function return types
• C-STRUCT-BOUNDS: Only the HexToBytesIter has trait bounds (on Iterator)

[tcharding]

Dependability section:

• C-VALIDATE: Manually checked all public functions.
• C-DTOR-FAIL and C-DTOR-BLOCK: There are no custom Drop imlps

[tcharding]

checked off up to here (excluding #136 stuff)

[tcharding]

Macros section:

• C-EVOCOTIVE: the hex test macro is deprecated, the impl_fmt_traits is evocotive already, and fmt_hex_exact is as evocotive as it can be IMO.
• C-MACRO-ATTR: Done, only applies to impl_fmt_traits
• C-ANYWHERE: Done in Test impl_fmt_traits in module scope #143
• C-MACRO-VIS: No visibility specifiers in the two remaining public macros
• C-MACRO-TY: No $t:ty in the macros

[tcharding]

Flexibility section:

• C-INTERMEDIATE: Done, we have two errors and the only one that could include intermediate data already does (position up to which the hex string is valid)
• C-CALLER-CONTROL: Done, only two instances of clone - both commented and correct.
• C-GENERIC: Done, manually checked all public functions
• C-OBJECT: Done, neither the DisplayHex or FromHex traits are dyn compatible because they both have associated types.

[tcharding]

Predictability section:

• C-SMART-PTR: Done, we don't have smart pointers here.
• C-CONV-SPECIFIC: Done, no real thinking required since this crate doesn't have typical data types
• C-METHOD: The only stand alone functions are the sered ones
• C-NO-OUT: Done, confirm with gg 'pub fn' | grep mut
• C-OVERLOAD: Done, no use of ops in this crate
• C-DEREF: No impls of Deref or DerefMut in this crate
• C-CTOR: Done, manually checked public functions

[tcharding]

Naming section:

• C-CASE: Done, pretty sure the linter catches these. I checked all public types just for good measure.
• C-CONV: Done, checked one as_ function and one into_ function - both correct.
• C-GETTER: Done, grepped for 'fn get'
• C-ITER: Done, there are no collections in this crate
• C-ITER-TY: Done, our iterators are kind of internal, and we construct them with explicit constructors
• C-FEATURE: Done, our only features are default, std, and alloc
• C-WORD-ORDER: Done, checked manually using output from contrib/api.sh types

[tcharding]

Interoperability section:

• C-CONV-TRAITS: Done, this crate doesn't have types with data that would suit as_ref, as_mu etc
• C-COLLECT: Done, there are no collections in this crate
• C-SERDE: Done, there are no types in this crate that play the role of a data structure
• C-NUM-FMT: Done, there are no number types in this crate
• C-RW-VALUE: Done in Document and test HexWriter constructor #144

[tcharding]

Crushing checklists like its my job - only docs to go.

[tcharding]

C-DEBUG and C-DEBUG-NONEMPTY were both done in #145.

[tcharding]

As were C-SEND-SYNC and C-GOOD-ERR

[Kixunil]

I don't believe C-SEALED is actually resolved so I reopened the issue and unchecked it.

[tcharding]

Mad, thanks for looking.

[tcharding]

C-SEALED done in #152.

[tcharding]

Documentation section

• C-QUESTION-MARK: Done, check by grepping with gg unwrap | grep //
• C-FAILURE: Have PR in flight (Improve the docs #160) for # Error.
• C-LINK: A quick grep for backtick and the output looks ok to me.
• C-METADATA: Done, we release crates for a living.
• C-RELNOTES: Done, noticed the 0.1.2 release notes were missing from master

Still TODO: A final once over of the whole crate, specificall C-CRATE-DOC, C-EXAMPLE, C-HIDDEN.