Add readme

.github/workflows/readme.yml

@@ -0,0 +1,26 @@
+name: Check README
+
+on:
+  pull_request:
+    branches: [ "*" ]
+
+env:
+  CARGO_TERM_COLOR: always
+  CARGO_NET_GIT_FETCH_WITH_CLI: true
+
+jobs:
+  check_readme:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+    - name: Install cargo-hakari
+      uses: baptiste0928/cargo-install@v1
+      with:
+        crate: cargo-readme
+    - name: Check that readme matches lib.rs
+      run: |
+        cp README.md README-copy.md
+        cp udigest-derive/README.md udigest-derive/README-copy.md
+        make readme
+        diff README.md README-copy.md
+        diff udigest-derive/README.md udigest-derive/README-copy.md

Makefile

@@ -0,0 +1,7 @@
+readme:
+	cargo readme -i src/lib.rs -r udigest/ -t ../docs/readme.tpl \
+		| perl -ne 's/\[(.+?)\]\(.+?\)/\1/g; print;' \
+		| perl -ne 's/(?<!#)\[(.+?)\]/\1/g; print;' \
+		> README.md
+	cargo readme -i src/lib.rs -r udigest-derive/ -t ../docs/readme.tpl \
+		> udigest-derive/README.md

README.md

@@ -0,0 +1,46 @@
+## Unambiguously digest structured data
+
+`udigest` provides utilities for unambiguous hashing the structured data. Structured
+data can be anything that implements `Digestable` trait:
+
+* `str`, `String`, `CStr`, `CString`
+* Integers:
+  `i8`, `i16`, `i32`, `i64`, `i128`,
+  `u8`, `u16`, `u32`, `u64`, `u128`,
+  `char`
+* Containers: `Box`, `Arc`, `Rc`, `Cow`, `Option`, `Result`
+* Collections: arrays, slices, `Vec`, `LinkedList`, `VecDeque`, `BTreeSet`, `BTreeMap`
+
+The trait is intentionally not implemented for certain types:
+
+* `HashMap`, `HashSet` as they can not be traversed in determenistic order
+* `usize`, `isize` as their byte size varies on differnet platforms
+
+The `Digestable` trait can be implemented for the struct using a macro:
+```rust
+use udigest::{Tag, udigest};
+use sha2::Sha256;
+
+#[derive(udigest::Digestable)]
+struct Person {
+    name: String,
+    job_title: String,
+}
+let alice = &Person {
+    name: "Alice".into(),
+    job_title: "cryptographer".into(),
+};
+
+let tag = Tag::<Sha256>::new("udigest.example");
+let hash = udigest(tag, &alice);
+```
+
+The crate intentionally does not try to follow any existing standards for unambiguous
+encoding. The format for encoding was desingned specifically for `udigest` to provide
+a better usage experience in Rust. The details of encoding format can be found in
+`encoding` module.
+
+### Features
+* `std` implements `Digestable` trait for types in standard library
+* `alloc` implements `Digestable` trait for type in `alloc` crate
+* `derive` enables `Digestable` proc macro

docs/readme.tpl

@@ -0,0 +1 @@
+{{readme}}

udigest-derive/Cargo.toml

@@ -5,6 +5,7 @@ edition = "2021"
 
 [lib]
 proc-macro = true
+path = "src/lib.rs"
 
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 

udigest-derive/README.md

@@ -0,0 +1,5 @@
+### Proc macro for `udigest` crate
+
+This crate contains a proc macro for implementing `Digestable` trait
+from [udigest crate](https://docs.rs/udigest), please refer to its
+documentation.

udigest-derive/src/lib.rs

@@ -1,3 +1,9 @@
+//! ## Proc macro for `udigest` crate
+//!
+//! This crate contains a proc macro for implementing `Digestable` trait
+//! from [udigest crate](https://docs.rs/udigest), please refer to its
+//! documentation.
+
 use quote::{quote, quote_spanned};
 use syn::{spanned::Spanned, Error, Result};
 

udigest/Cargo.toml

@@ -2,8 +2,14 @@
 name = "udigest"
 version = "0.1.0"
 edition = "2021"
-
-[package.metadata."docs.rs"]
+license = "MIT OR Apache-2.0"
+description = "Unambiguously digest structured data"
+repository = "https://github.com/dfns/udigest"
+categories = ["algorithms", "cryptography", "no-std", "no-std::no-alloc"]
+keywords = ["hashing", "unambiguous encoding"]
+readme = "../README.md"
+
+[package.metadata.docs.rs]
 all-features = true
 
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html

udigest/src/lib.rs

@@ -1,4 +1,4 @@
-//! Unambiguously digest structured data
+//! # Unambiguously digest structured data
 //!
 //! `udigest` provides utilities for unambiguous hashing the structured data. Structured
 //! data can be anything that implements [`Digestable`] trait:
@@ -37,8 +37,13 @@
 //!
 //! The crate intentionally does not try to follow any existing standards for unambiguous
 //! encoding. The format for encoding was desingned specifically for `udigest` to provide
-//! a better usage experience in Rust. The details of encoding format can be found
-//! [here](encoding).
+//! a better usage experience in Rust. The details of encoding format can be found in
+//! [`encoding` module](encoding).
+//!
+//! ## Features
+//! * `std` implements `Digestable` trait for types in standard library
+//! * `alloc` implements `Digestable` trait for type in `alloc` crate
+//! * `derive` enables `Digestable` proc macro
 
 #![no_std]
 #![forbid(missing_docs)]