ed448: add documentation

ed25519/tests/pkcs8.rs

@@ -1,7 +1,6 @@
 //! PKCS#8 private key tests
 
 #![cfg(feature = "pkcs8")]
-
 use ed25519::pkcs8::{DecodePrivateKey, DecodePublicKey, KeypairBytes, PublicKeyBytes};
 use hex_literal::hex;
 

ed448/Cargo.toml

@@ -10,7 +10,7 @@ support library providing signature type definitions and PKCS#8 private key
 decoding/encoding support
 """
 documentation = "https://docs.rs/ed448-signature"
-repository = "https://github.com/RustCrypto/signatures/tree/master/ed448-signature"
+repository = "https://github.com/RustCrypto/signatures/tree/master/ed448"
 readme = "README.md"
 categories = ["cryptography", "no-std"]
 keywords = ["crypto", "curve448", "ecc", "signature", "signing"]

ed448/README.md

@@ -1,11 +1,23 @@
 # [RustCrypto]: Ed448
 
+[![crate][crate-image]][crate-link]
+[![Docs][docs-image]][docs-link]
+[![Build Status][build-image]][build-link]
+![Apache2/MIT licensed][license-image]
+![Rust Version][rustc-image]
+[![Project Chat][chat-image]][chat-link]
+
 [Edwards Digital Signature Algorithm (EdDSA)][1] over Curve448 as specified
 in [RFC 7748][2].
 
+[Documentation][docs-link]
+
 ## About
 
-This crate doesn't contain an implementation of Ed448.
+This crate doesn't contain an implementation of Ed448, but instead
+contains an [`ed448_signature::Signature`][3] type which other crates can use in
+conjunction with the [`signature::Signer`][4] and [`signature::Verifier`][5]
+traits.
 
 These traits allow crates which produce and consume Ed448 signatures
 to be written abstractly in such a way that different signer/verifier
@@ -43,6 +55,19 @@ Unless you explicitly state otherwise, any contribution intentionally submitted
 for inclusion in the work by you, as defined in the Apache-2.0 license, shall be
 dual licensed as above, without any additional terms or conditions.
 
+[//]: # (badges)
+
+[crate-image]: https://buildstats.info/crate/ed448-signature
+[crate-link]: https://crates.io/crates/ed448-signature
+[docs-image]: https://docs.rs/ed448-signature/badge.svg
+[docs-link]: https://docs.rs/ed448-signature/
+[build-image]: https://github.com/RustCrypto/signatures/actions/workflows/ed448.yml/badge.svg
+[build-link]: https://github.com/RustCrypto/signatures/actions/workflows/ed448.yml
+[license-image]: https://img.shields.io/badge/license-Apache2.0/MIT-blue.svg
+[rustc-image]: https://img.shields.io/badge/rustc-1.60+-blue.svg
+[chat-image]: https://img.shields.io/badge/zulip-join_chat-blue.svg
+[chat-link]: https://rustcrypto.zulipchat.com/#narrow/stream/260048-signatures
+
 [//]: # (links)
 
 [RustCrypto]: https://github.com/RustCrypto
@@ -51,3 +76,6 @@ dual licensed as above, without any additional terms or conditions.
 
 [1]: https://en.wikipedia.org/wiki/EdDSA#Ed448
 [2]: https://tools.ietf.org/html/rfc7748
+[3]: https://docs.rs/ed448-signature/latest/ed448-signature/struct.Signature.html
+[4]: https://docs.rs/signature/latest/signature/trait.Signer.html
+[5]: https://docs.rs/signature/latest/signature/trait.Verifier.html

ed448/src/lib.rs

@@ -1,7 +1,73 @@
 #![no_std]
+#![cfg_attr(docsrs, feature(doc_auto_cfg))]
 #![doc = include_str!("../README.md")]
+#![doc(html_logo_url = "https://raw.githubusercontent.com/RustCrypto/meta/master/logo_small.png")]
 #![allow(non_snake_case)]
 #![forbid(unsafe_code)]
+#![warn(
+    clippy::unwrap_used,
+    missing_docs,
+    rust_2018_idioms,
+    unused_lifetimes,
+    unused_qualifications
+)]
+
+//! # Using Ed448 generically over algorithm implementations/providers
+//!
+//! By using the `ed448-signature` crate, you can write code which signs and verifies
+//! messages using the Ed448 signature algorithm generically over any
+//! supported Ed448 implementation (see the next section for available
+//! providers).
+//!
+//! This allows consumers of your code to plug in whatever implementation they
+//! want to use without having to add all potential Ed448 libraries you'd
+//! like to support as optional dependencies.
+//!
+//! ## Example
+//!
+//! ```
+//! use ed448_signature::signature::{Signer, Verifier};
+//!
+//! pub struct HelloSigner<S>
+//! where
+//!     S: Signer<ed448_signature::Signature>
+//! {
+//!     pub signing_key: S
+//! }
+//!
+//! impl<S> HelloSigner<S>
+//! where
+//!     S: Signer<ed448_signature::Signature>
+//! {
+//!     pub fn sign(&self, person: &str) -> ed448_signature::Signature {
+//!         // NOTE: use `try_sign` if you'd like to be able to handle
+//!         // errors from external signing services/devices (e.g. HSM/KMS)
+//!         // <https://docs.rs/signature/latest/signature/trait.Signer.html#tymethod.try_sign>
+//!         self.signing_key.sign(format_message(person).as_bytes())
+//!     }
+//! }
+//!
+//! pub struct HelloVerifier<V> {
+//!     pub verifying_key: V
+//! }
+//!
+//! impl<V> HelloVerifier<V>
+//! where
+//!     V: Verifier<ed448_signature::Signature>
+//! {
+//!     pub fn verify(
+//!         &self,
+//!         person: &str,
+//!         signature: &ed448_signature::Signature
+//!     ) -> Result<(), ed448_signature::Error> {
+//!         self.verifying_key.verify(format_message(person).as_bytes(), signature)
+//!     }
+//! }
+//!
+//! fn format_message(person: &str) -> String {
+//!     format!("Hello, {}!", person)
+//! }
+//! ```
 
 mod hex;
 

ed448/tests/pkcs8.rs

@@ -1,7 +1,6 @@
 //! PKCS#8 private key tests
 
 #![cfg(feature = "pkcs8")]
-
 use ed448_signature::pkcs8::{DecodePrivateKey, DecodePublicKey, KeypairBytes, PublicKeyBytes};
 use hex_literal::hex;