added some docs (#3)

Cargo.toml

@@ -1,5 +1,6 @@
 [package]
 name = "drand-client-rs"
+description = "A small rust library for retrieving random numbers from drand"
 version = "0.1.0"
 edition = "2021"
 

src/http.rs

@@ -1,5 +1,11 @@
+//! # http
+//!
+//! basic HTTP connectors
+//!
+
 use crate::{Transport, TransportError};
 use reqwest::blocking::Client;
+
 use reqwest::StatusCode;
 
 pub struct HttpTransport {
@@ -24,6 +30,7 @@ impl Transport for HttpTransport {
     }
 }
 
+/// a simple implementation of the `Transport` trait using `reqwest` for HTTP endpoints
 pub fn new_http_transport() -> HttpTransport {
     HttpTransport {
         client: Client::new(),

src/lib.rs

@@ -1,21 +1,30 @@
+//! # drand-client-rs
+//!
+//! `drand_client_rs` is a small rust library for retrieving random numbers from the [drand network](https://drand.love).
+//!
+
 extern crate core;
 
-mod chain_info;
-mod http;
-mod verify;
+pub mod chain_info;
+pub mod http;
+pub mod verify;
 
 use crate::chain_info::ChainInfo;
 use crate::http::{new_http_transport, HttpTransport};
 use crate::verify::{verify_beacon, Beacon};
 use crate::DrandClientError::{InvalidChainInfo, InvalidRound};
 use thiserror::Error;
 
+/// a struct encapsulating all the necessary state for retrieving and validating drand beacons.
 pub struct DrandClient<'a, T: Transport> {
     transport: T,
     base_url: &'a str,
     chain_info: ChainInfo,
 }
 
+/// create a new instance of the client with an HTTP transport for a given `base_url`.
+/// Supported `base_url`s include: "<https://api.drand.sh>", "<https://drand.cloudflare.com>" and "<https://api.drand.secureweb3.com:6875>".
+/// A full list can be found at <https://drand.love/developer/>
 pub fn new_http_client(base_url: &str) -> Result<DrandClient<HttpTransport>, DrandClientError> {
     let http_transport = new_http_transport();
     let chain_info = fetch_chain_info(&http_transport, base_url)?;
@@ -26,10 +35,14 @@ pub fn new_http_client(base_url: &str) -> Result<DrandClient<HttpTransport>, Dra
     })
 }
 
+/// represents a transport on which to connect to the drand network. This crate provides an
+/// HTTP transport out of the box, which can be created by calling `new_http_transport()`
 pub trait Transport {
     fn fetch(&self, url: &str) -> Result<String, TransportError>;
 }
 
+/// fetch the chain info for a given URL. The chain info contains the public key (used to
+/// verify beacons) and the genesis time (used to calculate the time for given rounds).
 pub fn fetch_chain_info(
     transport: &HttpTransport,
     base_url: &str,
@@ -44,11 +57,14 @@ pub fn fetch_chain_info(
     }
 }
 
+/// an implementation of the logic for retrieving randomness
 impl<'a, T: Transport> DrandClient<'a, T> {
+    /// fetch the latest available randomness beacon
     pub fn latest_randomness(&self) -> Result<Beacon, DrandClientError> {
         self.fetch_beacon_tag("latest")
     }
 
+    /// fetch a randomness beacon for a specific round
     pub fn randomness(&self, round_number: u64) -> Result<Beacon, DrandClientError> {
         if round_number == 0 {
             Err(InvalidRound)

src/verify.rs

@@ -1,3 +1,9 @@
+//! # verify
+//!
+//! this module contains some of the cruptographic internals that some users might wish to use
+//! manually without the client
+//!
+
 use bls12_381::hash_to_curve::{ExpandMsgXmd, HashToCurve};
 use bls12_381::{
     multi_miller_loop, G1Affine, G1Projective, G2Affine, G2Prepared, G2Projective, Gt,
@@ -70,6 +76,7 @@ pub enum VerificationError {
     InvalidRandomness,
 }
 
+/// verify a randomness beacon for a given scheme and public key
 pub fn verify_beacon(
     scheme_id: &SchemeID,
     public_key: &[u8],
@@ -127,6 +134,8 @@ fn chained_beacon_message(beacon: &Beacon) -> Result<Vec<u8>, VerificationError>
     }
 }
 
+/// verify a signature where the public key is on g1 and the signature is on g2 for a
+/// given domain separation tag
 pub fn verify_on_g2(
     public_key: &[u8],
     message: &[u8],
@@ -180,6 +189,8 @@ pub fn verify_on_g2(
     }
 }
 
+/// verify a signature where the public key is on g2 and the signature is on g1 for a
+/// given domain separation tag
 pub fn verify_on_g1(
     public_key: &[u8],
     message: &[u8],