Merge #160: Improve the docs

729f739 Grab missing changelog from 0.1.2 release (Tobin C. Harding)
1c2ba8d Remove documentation from manifest (Tobin C. Harding)
3c51bd0 doc: Add Errors section crate wide (Tobin C. Harding)
5586feb Improve wrap_array example (Tobin C. Harding)
6e56f85 exapmles: Fix stale docs (Tobin C. Harding)
1ceb08b Add license to examples (Tobin C. Harding)

Pull request description:

  Docs y'all. Done as part of #125.

ACKs for top commit:
  apoelstra:
    ACK 729f739; successfully ran local tests

Tree-SHA512: e5778b535c939989a50f00fdb96f280fc806b1b41b199c5ee5e43c49ae6cf909eb49f7756e6dbca2e82cf59237e49ecba1dcc8991c217a8a3a04136d9bdeae4f

CHANGELOG.md

@@ -45,6 +45,10 @@ There are a bunch of breaking changes in this release, including:
 - Hide error internal [#44](https://github.com/rust-bitcoin/hex-conservative/pull/44)
 - Return specific error from `HexToByesIter::new` [#62](https://github.com/rust-bitcoin/hex-conservative/pull/62)
 
+# 0.1.2 - 2024-05-14
+
+- Fix bug in output of `InvalidError` [#88](https://github.com/rust-bitcoin/hex-conservative/pull/88).
+
 # 0.1.1 - 2023-07-19
 
 - [Add `test_hex_unwrap`](https://github.com/rust-bitcoin/hex-conservative/pull/24) hex parsing macro for test usage.

Cargo.toml

@@ -4,7 +4,6 @@ version = "0.3.0"
 authors = ["Martin Habovštiak <martin.habovstiak@gmail.com>", "Andrew Poelstra <apoelstra@wpsoftware.net>"]
 license = "CC0-1.0"
 repository = "https://github.com/rust-bitcoin/hex-conservative"
-documentation = "https://docs.rs/hex-conservative/"
 description = "A hex encoding and decoding crate with a conservative MSRV and dependency policy."
 categories = ["encoding"]
 keywords = ["encoding", "hex", "hexadecimal"]
@@ -43,3 +42,7 @@ name = "wrap_array"
 [[example]]
 name = "serde"
 required-features = ["std", "serde"]
+
+
+[lints.clippy]
+missing_errors_doc = "warn"

examples/hexy.rs

@@ -1,7 +1,9 @@
+// SPDX-License-Identifier: CC0-1.0
+
 //! Demonstrate hexadecimal encoding and decoding for a type with a natural hex representation.
 //!
 //! For a type where hex is supported but is not the natural representation see `./custom.rs`.
-//! To wrap an array see the `./wrap_array_*` examples.
+//! To wrap an array see the `./wrap_array.rs` example.
 
 use std::fmt;
 use std::str::FromStr;

examples/serde.rs

@@ -1,3 +1,5 @@
+// SPDX-License-Identifier: CC0-1.0
+
 //! Demonstrate how to use the serde module with struct fields.
 
 #![allow(clippy::disallowed_names)] // Foo is a valid name.

examples/wrap_array.rs

@@ -34,11 +34,15 @@ fn main() {
     println!("Debug: {:?}", wrap);
     println!("Debug pretty: {:#?}", wrap);
 
-    // We cannot call `to_lower_hex_string` on the wrapped type to allocate a string, if you wish to
-    // use that trait method see `./wrap_array_display_hex_trait.rs`.
-    let array_hex = array.as_hex().to_string();
-    let wrap_hex = wrap.to_string();
-    assert_eq!(array_hex, wrap_hex);
+    #[cfg(feature = "alloc")]
+    {
+        let array_hex = array.to_lower_hex_string();
+        let other = array.as_hex().to_string();
+        assert_eq!(array_hex, other);
+
+        let wrap_hex = wrap.to_string();
+        assert_eq!(array_hex, wrap_hex);
+    }
 }
 
 pub struct Wrap([u8; 32]);

src/display.rs

@@ -633,6 +633,8 @@ impl<T> std::io::Write for HexWriter<T>
 where
     T: core::fmt::Write,
 {
+    /// Writes `buf` into [`HexWriter`].
+    ///
     /// # Errors
     ///
     /// If no bytes could be written to this `HexWriter`, and the provided buffer is not empty,
@@ -653,6 +655,12 @@ where
             Ok(n)
         }
     }
+
+    /// `flush` is a no-op for [`HexWriter`].
+    ///
+    /// # Errors
+    ///
+    /// [`HexWriter`] never errors when flushing.
     fn flush(&mut self) -> Result<(), std::io::Error> { Ok(()) }
 }
 

src/parse.rs

@@ -18,6 +18,10 @@ pub trait FromHex: Sized + sealed::Sealed {
     type Error: Sized + fmt::Debug + fmt::Display;
 
     /// Produces an object from a hex string.
+    ///
+    /// # Errors
+    ///
+    /// Errors if parsing of hex string fails for any reason.
     fn from_hex(s: &str) -> Result<Self, Self::Error>;
 }
 

src/serde.rs

@@ -29,6 +29,10 @@ use crate::prelude::*;
 ///
 /// We only serialize as hex if the serializer is human readable, if not we call through to the
 /// `Serialize` implementation for `data`.
+///
+/// # Errors
+///
+/// Returns the serializer error if one occurs.
 pub fn serialize<S, T>(data: T, s: S) -> Result<S::Ok, S::Error>
 where
     S: Serializer,
@@ -41,6 +45,10 @@ where
 ///
 /// We only serialize as hex if the serializer is human readable, if not we call through to the
 /// `Serialize` implementation for `data`.
+///
+/// # Errors
+///
+/// Returns the serializer error if one occurs.
 pub fn serialize_lower<S, T>(data: T, serializer: S) -> Result<S::Ok, S::Error>
 where
     S: Serializer,
@@ -58,6 +66,10 @@ where
 ///
 /// We only serialize as hex if the serializer is human readable, if not we call through to the
 /// `Serialize` implementation for `data`.
+///
+/// # Errors
+///
+/// Returns the serializer error if one occurs.
 pub fn serialize_upper<S, T>(data: T, serializer: S) -> Result<S::Ok, S::Error>
 where
     S: Serializer,
@@ -116,6 +128,10 @@ impl serde::Serialize for SerializeBytesAsHexUpper<'_> {
 ///
 /// We only deserialize from hex if the serializer is human readable, if not we call through to the
 /// `Deserialize` implementation for `T`.
+///
+/// # Errors
+///
+/// Returns the deserializer error if one occurs.
 pub fn deserialize<'de, D, T>(d: D) -> Result<T, D::Error>
 where
     D: Deserializer<'de>,