Basic documentation.

Closes #1.

Cargo.toml

@@ -1,9 +1,10 @@
 [package]
 name = "rusty_secrets"
 version = "0.0.2"
+authors = ["Frederic Jacobs <github@fredericjacobs.com>", "sellibitze"]
 description = "Implementation of threshold Shamir secret sharing in the Rust programming language."
 homepage = "https://github.com/freedomofpress/RustySecrets"
-license = "GPLv3"
+license = "GPL-3.0"
 readme = "README.md"
 build = "build.rs"
 
@@ -20,3 +21,4 @@ crate_type = ["rlib"]
 [[bin]]
 name = "rusty_secrets_bin"
 path = "src/main.rs"
+doc = false

README.md

@@ -1,4 +1,6 @@
-# Rusty Secrets ![Travis-Badge](https://travis-ci.org/freedomofpress/RustySecrets.svg) [![Coverage Status](https://coveralls.io/repos/github/freedomofpress/RustySecrets/badge.svg?branch=master)](https://coveralls.io/github/freedomofpress/RustySecrets?branch=master)
+# Rusty Secrets [![Build Status](https://travis-ci.org/freedomofpress/RustySecrets.svg?branch=master)](https://travis-ci.org/freedomofpress/RustySecrets) [![Coverage Status](https://coveralls.io/repos/github/freedomofpress/RustySecrets/badge.svg?branch=master)](https://coveralls.io/github/freedomofpress/RustySecrets?branch=master)
+
+[**Documentation**](http://freedomofpress.github.io/RustySecrets/rusty_secrets/index.html)
 
 Rusty Secrets is an implementation of a threshold [Shamir's secret sharing scheme](https://en.wikipedia.org/wiki/Shamir%27s_Secret_Sharing).
 
@@ -65,10 +67,6 @@ $ echo -e "2-2-YJZQDGm22Y77Gw \n 2-4-F7rAjX3UOa53KA" | ./rusty_secrets_bin -d
 My secret
 ```
 
-### Library
-
-Documentation to come for the library interface.
-
 ## Vocabulary
 
 - Dealer: Entity that will perform key splitting from a master secret

src/lib/custom_error.rs

@@ -6,6 +6,7 @@ use std::fmt;
 use std::io;
 use std::num;
 
+/// Error struct used for generating an io:Error from a generic description.
 #[derive(Debug)]
 pub struct Error {
     descr: &'static str,
@@ -38,6 +39,8 @@ impl convert::From<Error> for io::Error {
     }
 }
 
+/// Returns an io:Error from description string and optional detail string.
+/// Particularly useful in Result expressions.
 pub fn other_io_err(descr: &'static str, detail: Option<String>) -> io::Error {
     convert::From::from(
         Error::new(descr, detail)

src/lib/mod.rs

@@ -2,18 +2,35 @@ extern crate rustc_serialize as serialize;
 extern crate rand;
 
 use self::rand::{ Rng, OsRng };
-pub use self::serialize::base64::{ self, FromBase64, ToBase64 };
+use self::serialize::base64::{ self, FromBase64, ToBase64 };
 
 mod gf256;
 use self::gf256::Gf256;
 
 use std::io;
-pub use std::str;
 use std::iter::repeat;
 
+/// Generate generic errors that typeset with io::Error.
 pub mod custom_error;
 use self::custom_error::*;
 
+
+/// Performs threshold k-out-of-n Shamir secret sharing.
+///
+/// # Examples
+///
+/// ```
+/// use rusty_secrets::{generate_shares};
+/// let secret = "These programs were never about terrorism: they’re about economic spying, social control, and diplomatic manipulation. They’re about power.".to_string();
+///
+/// match generate_shares(7, 10, &secret.into_bytes()){
+/// 	Ok(shares) => {
+/// 		// Do something with the shares
+/// 	},
+/// 	Err(_) => {}// Deal with error}
+/// }
+/// ```
+
 pub fn generate_shares(k: u8, n: u8, secret: &Vec<u8>) -> io::Result<Vec<String>> {
 	if k > n {
 		return Err(other_io_err("Threshold K can not be larger than N", None));
@@ -36,7 +53,7 @@ pub fn generate_shares(k: u8, n: u8, secret: &Vec<u8>) -> io::Result<Vec<String>
 	Ok(result)
 }
 
-pub fn process_shares(shares_strings: Vec<String>) -> io::Result<(u8, Vec<(u8,Vec<u8>)>)> {
+fn process_shares(shares_strings: Vec<String>) -> io::Result<(u8, Vec<(u8,Vec<u8>)>)> {
 	let mut opt_k_l: Option<(u8, usize)> = None;
 	let mut counter = 0u8;
 	let mut shares: Vec<(u8,Vec<u8>)> = Vec::new();
@@ -85,8 +102,29 @@ pub fn process_shares(shares_strings: Vec<String>) -> io::Result<(u8, Vec<(u8,Ve
 	Err(other_io_err("Not enough shares provided!", None))
 }
 
-pub fn recover_secret(shares_strings: Vec<String>) -> io::Result<Vec<u8>> {
+/// Recovers the secret from a k-out-of-n Shamir secret sharing.
-	let (k, shares) = try!(process_shares(shares_strings));
+///
+/// At least `k` distinct shares need to be provided to recover the share.
+///
+/// # Examples
+///
+/// ```
+/// use rusty_secrets::{recover_secret};
+/// let share1 = "2-1-1YAYwmOHqZ69jA".to_string();
+/// let share2 = "2-4-F7rAjX3UOa53KA".to_string();
+/// let shares = vec![share1, share2];
+///
+/// match recover_secret(shares) {
+/// 	Ok(secret) => {
+/// 		// Do something with the secret
+/// 	},
+/// 	Err(e) => {
+/// 		// Deal with the error
+/// 	}
+/// }
+/// ```
+pub fn recover_secret(shares: Vec<String>) -> io::Result<Vec<u8>> {
+	let (k, shares) = try!(process_shares(shares));
 
 	let slen = shares[0].1.len();
 	let mut col_in = Vec::with_capacity(k as usize);