Minor fixups and doc updates.

src/lib.rs

@@ -1,12 +1,28 @@
 //! emsha is the embedded hashing library. It aims to work even in
 //! nostdenv environments.
+//!
+//! ## Example SHA256 hashing
+//! ```
+//! use emsha::{Hash, sha256};
+//! # use emsha::Result;
+//! # fn main() -> Result<()> {
+//! let mut h = sha256::SHA256::new();
+//! let mut d: [u8; sha256::SIZE] = [0; sha256::SIZE];
+//! h.update(b"hello, world!")?;
+//! h.finalize(&mut d)?;
+//! println!("{:?}", d);
+//! # Ok(())
+//! # }
+//! ```
 
 #![no_std]
+#![warn(missing_docs)]
 
 use core::error;
 use core::fmt;
 
 #[derive(Clone, Debug)]
+/// Error is a standardized error type for the emsha package.
 pub struct Error {
     reason: Code,
 }
@@ -16,7 +32,6 @@ impl fmt::Display for Error {
         match self.reason {
             Code::Unknown => write!(f, "unknown error"),
             Code::OK => write!(f, "OK"),
-            Code::TestFailure => write!(f, "test failure"),
             Code::InvalidState => write!(f, "invalid state"),
             Code::InputTooLong => write!(f, "input is too long"),
             Code::BufferTooSmall => {
@@ -30,6 +45,7 @@ impl fmt::Display for Error {
 }
 
 impl Error {
+    /// Construct an error with a `emsha::Code`.
     pub fn with(reason: Code) -> Self {
         Self { reason }
     }
@@ -38,18 +54,33 @@ impl Error {
 impl error::Error for Error {}
 
 #[derive(Clone, Copy, Debug, PartialEq)]
+/// Common error codes for emsha.
 pub enum Code {
-    Unknown,
+    /// This is used internally to denote a Hash is in a good state.
     OK,
-    TestFailure,
+
+    /// The Hash is in an invalid state and cannot be used except
+    /// maybe via a reset. This is a serious issue.
     InvalidState,
+
+    /// The input passed to the hash is too long.
     InputTooLong,
+
+    /// A buffer passed to a hash function was not large enough.
     BufferTooSmall,
+
+    /// An attempt was made to get the result of a hash before it was
+    /// finalized.
     HashNotFinalized,
+
+    /// An unknown error has occurred.
+    Unknown,
 }
 
+/// Result is a convenience type for results returned from this package.
 pub type Result<T> = core::result::Result<T, Error>;
 
+/// Hash implements a secure hashing algorithm.
 pub trait Hash {
     /// Bring the Hash back to its initial state.
     ///
@@ -82,12 +113,6 @@ pub trait Hash {
     /// The Hash must keep enough state for repeated calls to result
     /// to work.
     fn result(&self, digest: &mut [u8]) -> Result<()>;
-
-    /// Return the output size of the Hash.
-    ///
-    /// This is how large the buffers written to by result should
-    /// be.
-    fn size() -> usize;
 }
 
 mod common;