Improve crate documentation

With upcoming decoding stabilization we need to inform users about
details of the stabilization and make sure our API doc is
understandable. This makes various doc improvements including explaining
how we're going to stabilize things and feature flags.

Author: Kixunil

README.md

@@ -2,6 +2,30 @@
 
 General purpose hex encoding/decoding library with a conservative MSRV and dependency policy.
 
+## Stabilization strategy
+
+Because downstream crates may need to return hex errors in their APIs and they need to be
+stabilized soon, this crate only exposes the errors and two basic decoding functions. This
+should already help with the vast majority of the cases and we're sufficiently confident that
+these errors won't have a breaking change any time soon (possibly never).
+
+If you're writing a binary you don't need to worry about any of this and just use the unstable
+version for now. If you're writing a library you should use these stable errors in the API but
+you may internally depend on the unstable crate version to get the advanced features that won't
+affect your API. This way your API can stabilize before all features in this crate are fully
+stable and you still can use all of them.
+
+## Crate feature flags
+
+* `std` - enables the standard library, on by default.
+* `alloc` - enables features that require allocation such as decoding into `Vec<u8>`, implied
+by `std`.
+* `newer-rust-version` - enables Rust version detection and thus newer features, may add
+                         dependency on a feature detection crate to reduce compile times. This
+                         feature is expected to do nothing once the native detection is in Rust
+                         and our MSRV is at least that version. We may also remove the feature
+                         gate in 2.0 with semver trick once that happens.
+
 ## Minimum Supported Rust Version (MSRV)
 
 This library should compile with almost any combination of features on **Rust 1.63.0**, however we

src/error.rs

@@ -65,12 +65,18 @@ macro_rules! write_err {
 }
 pub(crate) use write_err;
 
-/// Hex decoding error.
+/// Error returned when hex decoding a hex string with variable length.
+///
+/// This represents the first error encountered during decoding, however we may add other remaining
+/// ones in the future.
+///
+/// This error differs from [`HexToArrayError`] in that the number of bytes is only known at
+/// run time - e.g. when decoding `Vec<u8>`.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub enum HexToBytesError {
     /// Non-hexadecimal character.
     InvalidChar(InvalidCharError),
-    /// Purported hex string had odd length.
+    /// Purported hex string had odd (not even) length.
     OddLengthString(OddLengthStringError),
 }
 
@@ -272,7 +278,10 @@ if_std_error! {{
     impl StdError for OddLengthStringError {}
 }}
 
-/// Hex decoding error.
+/// Error returned when hex decoding bytes whose length is known at compile time.
+///
+/// This error differs from [`HexToBytesError`] in that the number of bytes is known at
+/// compile time - e.g. when decoding to an array of bytes.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub enum HexToArrayError {
     /// Non-hexadecimal character.
@@ -364,9 +373,16 @@ impl From<Infallible> for InvalidLengthError {
 
 impl InvalidLengthError {
     /// Returns the expected length.
+    ///
+    /// Note that this represents both the number of bytes and the number of characters that needs
+    /// to be passed into the decoder, since the hex digits are ASCII and thus always 1-byte long.
     #[inline]
     pub fn expected_length(&self) -> usize { self.expected }
-    /// Returns the position of the invalid character byte.
+
+    /// Returns the number of *hex bytes* passed to the hex decoder.
+    ///
+    /// Note that this does not imply the number of characters nor hex digits since they may be
+    /// invalid (wide unicode chars).
     #[inline]
     pub fn invalid_length(&self) -> usize { self.invalid }
 }

src/lib.rs

@@ -34,6 +34,29 @@
 //! # }
 //! ```
 //!
+//! ## Stabilization strategy
+//!
+//! Because downstream crates may need to return hex errors in their APIs and they need to be
+//! stabilized soon, this crate only exposes the errors and two basic decoding functions. This
+//! should already help with the vast majority of the cases and we're sufficiently confident that
+//! these errors won't have a breaking change any time soon (possibly never).
+//!
+//! If you're writing a binary you don't need to worry about any of this and just use the unstable
+//! version for now. If you're writing a library you should use these stable errors in the API but
+//! you may internally depend on the unstable crate version to get the advanced features that won't
+//! affect your API. This way your API can stabilize before all features in this crate are fully
+//! stable and you still can use all of them.
+//!
+//! ## Crate feature flags
+//!
+//! * `std` - enables the standard library, on by default.
+//! * `alloc` - enables features that require allocation such as decoding into `Vec<u8>`, implied
+//!   by `std`.
+//! * `newer-rust-version` - enables Rust version detection and thus newer features, may add
+//!   dependency on a feature detection crate to reduce compile times. This feature is expected to
+//!   do nothing once the native detection is in Rust and our MSRV is at least that version. We may
+//!   also remove the feature gate in 2.0 with semver trick once that happens.
+//!
 //! ## MSRV policy
 //!
 //! The MSRV of the crate is currently 1.63.0 and we don't intend to bump it until the newer Rust
@@ -97,29 +120,37 @@ pub use self::{
     parse::FromHex,
 };
 
-/// Decodes a hex string into a vector of bytes.
+/// Decodes a hex string with variable length.
+///
+/// The length of the returned `Vec` is determined by the length of the input, meaning all even
+/// lengths of the input string are allowed. If you know the required length at compile time using
+/// [`decode_to_array`] is most likely a better choice.
 ///
 /// # Errors
 ///
-/// Errors if `s` is not a valid hex string.
+/// Returns an error if `hex` contains invalid characters or doesn't have even length.
 #[cfg(feature = "alloc")]
-pub fn decode_to_vec(s: &str) -> Result<Vec<u8>, HexToBytesError> {
-    Ok(HexToBytesIter::new(s)?.drain_to_vec()?)
+pub fn decode_to_vec(hex: &str) -> Result<Vec<u8>, HexToBytesError> {
+    Ok(HexToBytesIter::new(hex)?.drain_to_vec()?)
 }
 
-/// Decodes a hex string into an array of bytes.
+/// Decodes a hex string with an expected length kown at compile time.
+///
+/// If you don't know the required length at compile time you need to use [`decode_to_vec`]
+/// instead.
 ///
 /// # Errors
 ///
-/// Errors if `s` is not a valid hex string or the correct length.
-pub fn decode_to_array<const N: usize>(s: &str) -> Result<[u8; N], HexToArrayError> {
-    if s.len() == N * 2 {
+/// Returns an error if `hex` contains invalid characters or has incorrect length. (Should be
+/// `N * 2`.)
+pub fn decode_to_array<const N: usize>(hex: &str) -> Result<[u8; N], HexToArrayError> {
+    if hex.len() == N * 2 {
         let mut ret = [0u8; N];
         // checked above
-        HexToBytesIter::new_unchecked(s).drain_to_slice(&mut ret)?;
+        HexToBytesIter::new_unchecked(hex).drain_to_slice(&mut ret)?;
         Ok(ret)
     } else {
-        Err(InvalidLengthError { invalid: s.len(), expected: 2 * N }.into())
+        Err(InvalidLengthError { invalid: hex.len(), expected: 2 * N }.into())
     }
 }