Fill out rustdoc

src/claims.rs

@@ -5,12 +5,15 @@ use serde::{Deserialize, Serialize};
 use serde_json;
 use serde_json::value::{Value};
 
+/// A default claim set, including the standard, or registered, claims and the ability to specify
+/// your own as private claims.
 #[derive(Debug, Default, PartialEq)]
 pub struct Claims<T: Serialize + Deserialize> {
     pub reg: Registered,
     pub private: T
 }
 
+/// The registered claims from the spec.
 #[derive(Debug, Default, PartialEq, Serialize, Deserialize)]
 pub struct Registered {
     pub iss: Option<String>,
@@ -23,6 +26,7 @@ pub struct Registered {
 }
 
 impl<T: Serialize + Deserialize> Claims<T>{
+    /// Convenience factory method
     pub fn new(reg: Registered, private: T) -> Claims<T> {
         Claims {
             reg: reg,
@@ -32,6 +36,8 @@ impl<T: Serialize + Deserialize> Claims<T>{
 }
 
 impl<T: Serialize + Deserialize> Component for Claims<T> {
+    /// This implementation  simply parses the base64 data twice, each time applying it to the
+    /// registered and private claims.
     fn from_base64(raw: &str) -> Result<Claims<T>, Error> {
         let data = try!(decode_config(raw, URL_SAFE));
         let reg_claims: Registered = try!(serde_json::from_slice(&data));
@@ -45,6 +51,8 @@ impl<T: Serialize + Deserialize> Component for Claims<T> {
         })
     }
 
+    /// Renders both the registered and private claims into a single consolidated JSON
+    /// representation before encoding.
     fn to_base64(&self) -> Result<String, Error> {
         if let Value::Object(mut reg_map) = serde_json::to_value(&self.reg)? {
             if let Value::Object(pri_map) = serde_json::to_value(&self.private)? {

src/header.rs

@@ -1,6 +1,7 @@
 use std::default::Default;
 use Header;
 
+/// A default Header providing the type, key id and algorithm fields.
 #[derive(Debug, PartialEq, Serialize, Deserialize)]
 pub struct DefaultHeader {
     pub typ: Option<HeaderType>,
@@ -9,11 +10,13 @@ pub struct DefaultHeader {
 }
 
 
+/// Default value for the header type field.
 #[derive(Debug, PartialEq, Serialize, Deserialize)]
 pub enum HeaderType {
     JWT,
 }
 
+/// Supported algorithms, each representing a valid signature and digest combination.
 #[derive(Debug, PartialEq, Serialize, Deserialize)]
 pub enum Algorithm {
     HS256,
@@ -34,6 +37,8 @@ impl Default for DefaultHeader {
     }
 }
 
+/// Allow the rest of the library to access the configured algorithm without having to know the
+/// specific type for the header.
 impl Header for DefaultHeader {
     fn alg(&self) -> &Algorithm {
         &(self.alg)

src/lib.rs

@@ -18,6 +18,7 @@ pub mod header;
 pub mod claims;
 mod crypt;
 
+/// Main struct representing a JSON Web Token, composed of a header and a set of claims.
 #[derive(Debug, Default)]
 pub struct Token<H, C>
     where H: Component, C: Component {
@@ -26,15 +27,19 @@ pub struct Token<H, C>
     pub claims: C,
 }
 
+/// Any header type must implement this trait so that signing and verification work.
 pub trait Header {
     fn alg(&self) -> &header::Algorithm;
 }
 
+/// Any header or claims type must implement this trait in order to serialize and deserialize
+/// correctly.
 pub trait Component: Sized {
     fn from_base64(raw: &str) -> Result<Self, Error>;
     fn to_base64(&self) -> Result<String, Error>;
 }
 
+/// Provide a default implementation that should work in almost all cases.
 impl<T> Component for T
     where T: Serialize + Deserialize + Sized {
 
@@ -53,6 +58,7 @@ impl<T> Component for T
     }
 }
 
+/// Provide the ability to parse a token, verify it and sign/serialize it.
 impl<H, C> Token<H, C>
     where H: Component + Header, C: Component {
     pub fn new(header: H, claims: C) -> Token<H, C> {
@@ -74,7 +80,7 @@ impl<H, C> Token<H, C>
         })
     }
 
-    /// Verify a from_base64 token with a key and the token's specific algorithm
+    /// Verify a token with a key and the token's specific algorithm.
     pub fn verify(&self, key: &[u8]) -> bool {
         let raw = match self.raw {
             Some(ref s) => s,
@@ -88,7 +94,8 @@ impl<H, C> Token<H, C>
         crypt::verify(sig, data, key, &self.header.alg())
     }
 
-    /// Generate the signed token from a key and the specific algorithm
+    /// Generate the signed token from a key with the specific algorithm as a url-safe, base64
+    /// string.
     pub fn signed(&self, key: &[u8]) -> Result<String, Error> {
         let header = try!(Component::to_base64(&self.header));
         let claims = try!(self.claims.to_base64());