more documentation

2 files changed, 29 insertions, 0 deletions

diff --git a/src/error.rs b/src/error.rs
index 155a388..a79b8e0 100644
--- a/src/error.rs
+++ b/src/error.rs
@@ -1,13 +1,29 @@
+//! Error definitions for HIBE operations.
 use thiserror::Error;
 
+/// Type for all errors that can occur when working with the HIBE implementations of this crate.
 #[derive(Debug, Error)]
 pub enum Error {
+    /// Error returned when the identity that was supplied exceeded the given maximum hierarchy
+    /// depth.
+    ///
+    /// Can also be returned when trying to derive a key that would exceed the maximum identity
+    /// depth.
     #[error("The supplied identity was too long")]
     IdentityTooLong,
+
+    /// Error returned when trying to derive the root identity, as there is no parent key for the
+    /// root.
     #[error("The supplied identity had no elements")]
     EmptyIdentity,
+
+    /// Error when the given ciphertext was malformed.
+    ///
+    /// Note that this crate does not verify the integrity of ciphertexts. The absence of a
+    /// malformation therefore does *not* mean that the ciphertext has not been tampered with!
     #[error("The supplied ciphertext was malforemd")]
     MalformedCiphertext,
 }
 
+/// Shortcut for [`std::result::Result`] with [`enum@Error`] as the default error.
 pub type Result<V, E=Error> = std::result::Result<V, E>;
diff --git a/src/hibe/bbg.rs b/src/hibe/bbg.rs
index 06dbb51..28a3407 100644
--- a/src/hibe/bbg.rs
+++ b/src/hibe/bbg.rs
@@ -8,16 +8,29 @@ use bls12_381_plus::{
 };
 use rand::Rng;
 
+/// HIBE from Dan Boneh, Xavier Boyen and Eu-Jin Goh (2005).
+///
+/// This struct implements the HIBE of Boneh, Boyen and Goh from their paper "Hierarchical Identity
+/// Based Encryption with Constant Size Ciphertext" (2005) ([eprint][eprint]).
+///
+/// The underlying bilinear curve is BLS12-381.
+///
+/// [eprint]: https://eprint.iacr.org/2005/015.pdf
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct BonehBoyenGoh {
     max_depth: usize,
 }
 
 impl BonehBoyenGoh {
+    /// Constructs a new BBG HIBE algorithm suitable for identites up to the given depth.
+    ///
+    /// Note that this method only sets up the algorithm definition, it does not draw any keys yet.
+    /// See [`Hibe::setup`] for that.
     pub fn new(max_depth: usize) -> Self {
         Self { max_depth }
     }
 
+    /// Returns the maximum depth that this instance supports.
     pub fn max_depth(&self) -> usize {
         self.max_depth
     }