From 1971e224efa6a5940fb8b15c718f2b59c2d0f014 Mon Sep 17 00:00:00 2001
From: Julien Tanguy <julien.tanguy@jhome.fr>
Date: Thu, 9 Apr 2015 18:04:05 +0200
Subject: [PATCH] Documentation

---
 README.md                       |  1 +
 src/Crypto/Macaroon.hs          |  6 ++++++
 src/Crypto/Macaroon/Internal.hs | 10 ++++++++--
 3 files changed, 15 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 45b84e0..994cb4b 100644
--- a/README.md
+++ b/README.md
@@ -27,6 +27,7 @@ Implementations
 - [C](https://github.com/rescrv/libmacaroons)
 - [Java](https://github.com/nitram509/jmacaroons)
 - [Python](https://github.com/ecordell/pymacaroons)
+- [Node.js](https://github.com/nitram509/macaroons.js)
 
 TODO
 ====
diff --git a/src/Crypto/Macaroon.hs b/src/Crypto/Macaroon.hs
index 42e4a07..07043f7 100644
--- a/src/Crypto/Macaroon.hs
+++ b/src/Crypto/Macaroon.hs
@@ -25,6 +25,7 @@ module Crypto.Macaroon (
     , Caveat
     , Key
     , Location
+    , Sig
     -- * Accessing functions
     -- ** Macaroons
     , location
@@ -65,18 +66,23 @@ create secret ident loc = MkMacaroon loc ident [] (toBytes (hmac derivedKey iden
   where
     derivedKey = toBytes (hmac "macaroons-key-generator" secret :: HMAC SHA256)
 
+-- | Caveat target location
 caveatLoc :: Caveat -> Location
 caveatLoc = cl
 
+-- | Caveat identifier
 caveatId :: Caveat -> Key
 caveatId = cid
 
+-- | Caveat verification identifier
 caveatVId :: Caveat -> Key
 caveatVId = vid
 
+-- | Inspect a macaroon's contents. For debugging purposes.
 inspect :: Macaroon -> String
 inspect = show
 
+-- | Serialize a macaroon in an URL-safe Base64 encoding
 serialize :: Macaroon -> BS.ByteString
 serialize m = B8.filter (/= '=') . B64.encode $ packets
   where
diff --git a/src/Crypto/Macaroon/Internal.hs b/src/Crypto/Macaroon/Internal.hs
index 82ce0b4..810591c 100644
--- a/src/Crypto/Macaroon/Internal.hs
+++ b/src/Crypto/Macaroon/Internal.hs
@@ -27,9 +27,10 @@ import           Data.List
 -- |Type alias for Macaroons and Caveat keys and identifiers
 type Key = BS.ByteString
 
--- |Type alias For Macaroons and Caveat locations
+-- |Type alias for Macaroons and Caveat locations
 type Location = BS.ByteString
 
+-- |Type alias for Macaroons signatures
 type Sig = BS.ByteString
 
 -- | Main structure of a macaroon
@@ -43,6 +44,7 @@ data Macaroon = MkMacaroon { location   :: Location
                            -- ^ Macaroon HMAC signature
                            } deriving (Eq)
 
+-- | show instance conforming to the @inspect@ "specification"
 instance Show Macaroon where
     -- We use intercalate because unlines would add a trailing newline
     show (MkMacaroon l i c s) = intercalate "\n" [
@@ -52,6 +54,7 @@ instance Show Macaroon where
                     , "signature " ++ B8.unpack (hex s)
                     ]
 
+-- | NFData instance for use in the benchmark
 instance NFData Macaroon where
     rnf (MkMacaroon loc ident cavs sig) = rnf loc `seq` rnf ident `seq` rnf cavs `seq` rnf sig
 
@@ -66,6 +69,7 @@ data Caveat = MkCaveat { cid :: Key
 
                        } deriving (Eq)
 
+-- | show instance conforming to the @inspect@ "specification"
 instance Show Caveat where
     show (MkCaveat c v l) | v == BS.empty = "cid " ++ B8.unpack c
                           | otherwise = unlines [ "cid " ++ B8.unpack c
@@ -74,10 +78,12 @@ instance Show Caveat where
                                                 ]
 
 
+-- | NFData instance for use in the benchmark
 instance NFData Caveat where
     rnf (MkCaveat cid vid cl) = rnf cid `seq` rnf vid `seq` rnf cl
 
-
+-- | Primitive to add a First or Third party caveat to a macaroon
+-- For internal use only
 addCaveat :: Location
           -> Key
           -> Key
-- 
2.41.0