Commits

Bryan O'Sullivan committed e127309

A little documentation.

  • Participants
  • Parent commits 09dc6ec

Comments (0)

Files changed (4)

File src/Network/Riak/Connection/Internal.hs

 defaultClient = Client {
                   host = "127.0.0.1"
                 , port = "8087"
-                , prefix = "riak"
-                , mapReducePrefix = "mapred"
                 , clientID = L.empty
                 }
 

File src/Network/Riak/JSON.hs

 
 module Network.Riak.JSON
     (
-      JSON(plain)
+      JSON
     , json
+    , plain
     , get
     , getMany
     , put
 
 import Control.Applicative ((<$>))
 import Control.Arrow (first)
-import Data.Monoid (Dual(..), First(..), Last(..), Monoid)
+import Data.Monoid (Monoid)
 import Data.Typeable (Typeable)
 import Network.Riak.Types.Internal
 import Data.Aeson.Types (FromJSON(..), ToJSON(..))
 import qualified Network.Riak.Value as V
 
 newtype JSON a = J {
-      plain :: a
+      plain :: a -- ^ Unwrap a 'JSON'-wrapped value.
     } deriving (Eq, Ord, Show, Read, Bounded, Typeable, Monoid)
 
+-- | Wrap up a value so that it will be encoded and decoded as JSON
+-- when converted to/from 'Content'.
 json :: (FromJSON a, ToJSON a) => a -> JSON a
 json = J
 {-# INLINE json #-}
     fmap f (J a) = J (f a)
     {-# INLINE fmap #-}
 
-instance ToJSON a => ToJSON (Dual a) where
-    toJSON = toJSON . getDual
-    {-# INLINE toJSON #-}
-
-instance FromJSON a => FromJSON (Dual a) where
-    fromJSON = fmap Dual . fromJSON
-    {-# INLINE fromJSON #-}
-
-instance ToJSON a => ToJSON (First a) where
-    toJSON = toJSON . getFirst
-    {-# INLINE toJSON #-}
-
-instance FromJSON a => FromJSON (First a) where
-    fromJSON = fmap First . fromJSON
-    {-# INLINE fromJSON #-}
-
-instance ToJSON a => ToJSON (Last a) where
-    toJSON = toJSON . getLast
-    {-# INLINE toJSON #-}
-
-instance FromJSON a => FromJSON (Last a) where
-    fromJSON = fmap Last . fromJSON
-    {-# INLINE fromJSON #-}
-
 instance (FromJSON a, ToJSON a) => V.IsContent (JSON a) where
     fromContent c = J `fmap` (V.fromContent c >>= fromJSON)
     {-# INLINE fromContent #-}

File src/Network/Riak/JSON/Monoid.hs

     , putMany
     ) where
 
-import Data.Monoid (Monoid(..))
+import Data.Aeson.Types (FromJSON(..), ToJSON(..))
+import Data.Monoid (Dual(..), First(..), Last(..), Monoid)
 import Network.Riak.Types.Internal hiding (MessageTag(..))
-import Data.Aeson.Types (FromJSON, ToJSON)
 import qualified Network.Riak.JSON as J
 import qualified Network.Riak.Monoid as M
 
+instance ToJSON a => ToJSON (Dual a) where
+    toJSON = toJSON . getDual
+    {-# INLINE toJSON #-}
+
+instance FromJSON a => FromJSON (Dual a) where
+    fromJSON = fmap Dual . fromJSON
+    {-# INLINE fromJSON #-}
+
+instance ToJSON a => ToJSON (First a) where
+    toJSON = toJSON . getFirst
+    {-# INLINE toJSON #-}
+
+instance FromJSON a => FromJSON (First a) where
+    fromJSON = fmap First . fromJSON
+    {-# INLINE fromJSON #-}
+
+instance ToJSON a => ToJSON (Last a) where
+    toJSON = toJSON . getLast
+    {-# INLINE toJSON #-}
+
+instance FromJSON a => FromJSON (Last a) where
+    fromJSON = fmap Last . fromJSON
+    {-# INLINE fromJSON #-}
+
+-- | Retrieve a single value.  If conflicting values are returned, the
+-- 'Monoid' is used to choose a winner.
 get :: (FromJSON c, ToJSON c, Monoid c) =>
        Connection -> Bucket -> Key -> R -> IO (Maybe (c, VClock))
 get = M.get J.get
 {-# INLINE get #-}
 
+-- | Retrieve multiple values.  If conflicting values are returned for
+-- a value, the 'Monoid' is used to choose a winner.
 getMany :: (FromJSON c, ToJSON c, Monoid c)
-           => Connection -> Bucket -> [Key] -> R
-        -> IO [Maybe (c, VClock)]
+           => Connection -> Bucket -> [Key] -> R -> IO [Maybe (c, VClock)]
 getMany = M.getMany J.getMany
 {-# INLINE getMany #-}
 
+-- | Store a single value.  This function does not return until any
+-- vector clock conflicts are resolved.
 put :: (FromJSON c, ToJSON c, Monoid c) =>
        Connection -> Bucket -> Key -> Maybe VClock -> c -> W -> DW
     -> IO (c, VClock)
 put = M.put J.put
 {-# INLINE put #-}
 
+-- | Store multiple values.  This function does not return until any
+-- vector clock conflicts are resolved.
 putMany :: (FromJSON c, ToJSON c, Monoid c) =>
            Connection -> Bucket -> [(Key, Maybe VClock, c)] -> W -> DW
         -> IO [(c, VClock)]

File src/Network/Riak/Types/Internal.hs

 import Network.Socket (HostName, ServiceName, Socket)
 import Text.ProtocolBuffers (ReflectDescriptor, Wire)
     
+-- | A client identifier.  This is used by the Riak cluster when
+-- logging vector clock changes, and should be unique for each client.
 type ClientID = ByteString
 
 data Client = Client {
       host :: HostName
+    -- ^ Name of the server to connect to.
     , port :: ServiceName
-    , prefix :: ByteString
-    , mapReducePrefix :: ByteString
+    -- ^ Port number to connect to (default is 8087).
     , clientID :: ClientID
+    -- ^ Client identifier.
     } deriving (Eq, Show, Typeable)
 
+-- | A connection to a Riak server.
 data Connection = Connection {
       connSock :: Socket
     , connClient :: Client
+    -- ^ The configuration we connected with.
     , connBuffer :: IORef ByteString
+    -- ^ Received data that has not yet been consumed.
     } deriving (Eq)
 
+-- | The main Riak exception type.
 data RiakException = NetException {
       excModule :: String
     , excFunction :: String
     show conn = show "Connection " ++ host c ++ ":" ++ port c
         where c = connClient conn
 
+-- | A Bucket is a container and keyspace for data stored in Riak,
+-- with a set of common properties for its contents (the number of
+-- replicas, for instance).
 type Bucket = ByteString
 
+-- | Keys are unique object identifiers in Riak and are scoped within
+-- buckets.
 type Key = ByteString
 
+-- | An application-specific identifier for a link.  See
+-- <http://wiki.basho.com/Links.html> for details.
 type Tag = ByteString
 
+-- | A specification of a MapReduce
+-- job. <http://wiki.basho.com/MapReduce.html>.
 data Job = JSON ByteString
          | Erlang ByteString
            deriving (Eq, Show, Typeable)
 
+-- | An identifier for an inbound or outbound message.
 data MessageTag = ErrorResponse
                 | PingRequest
                 | PingResponse
                 | MapReduceResponse
                   deriving (Eq, Show, Enum, Typeable)
 
+-- | All messages are tagged.
 class Tagged msg where
     messageTag :: msg -> MessageTag
 
     messageTag m = m
     {-# INLINE messageTag #-}
 
-class (Tagged msg, ReflectDescriptor msg, Show msg, Wire msg) => Request msg where
-    expectedResponse :: msg -> MessageTag
+-- | A message representing a request from client to server.
+class (Tagged msg, ReflectDescriptor msg, Show msg, Wire msg) => Request msg
+    where expectedResponse :: msg -> MessageTag
 
+-- | A message representing a response from server to client.
 class (Tagged msg, ReflectDescriptor msg, Show msg, Wire msg) => Response msg
 
 class (Request req, Response resp) => Exchange req resp
     messageTag (Right r) = messageTag r
     {-# INLINE messageTag #-}
 
+-- | A wrapper that keeps Riak vector clocks opaque.
 newtype VClock = VClock {
       fromVClock :: ByteString
+    -- ^ Unwrap the 'ByteString'.  (This is really only useful for
+    -- printing the raw vclock string.)
     } deriving (Eq, Typeable)
 
 instance Show VClock where
     show (VClock s) = "VClock " ++ show (md5 s)
 
-data Quorum = Default
-            | One
-            | Quorum
-            | All
+-- | A read/write quorum.  The quantity of replicas that must respond
+-- to a read or write request before it is considered successful. This
+-- is defined as a bucket property or as one of the relevant
+-- parameters to a single request ('R','W','DW','RW').
+data Quorum = Default   -- ^ Use the default settings for the bucket.
+            | One       -- ^ Success after one server has responded.
+            | Quorum    -- ^ Success after a quorum of servers have responded.
+            | All       -- ^ Success after all servers have responded.
               deriving (Bounded, Eq, Enum, Ord, Show, Typeable)
 
+-- | Read/write quorum.  How many replicas need to collaborate when
+-- deleting a value.
 type RW = Quorum
+
+-- | Read quorum.  How many replicas need to agree when retrieving a
+-- value.
 type R  = Quorum
+
+-- | Write quorum.  How many replicas to write to before returning a
+-- successful response.
 type W  = Quorum
+
+-- | Durable write quorum.  How many replicas to commit to durable
+-- storage before returning a successful response.
 type DW = Quorum
 
 fromQuorum :: Quorum -> Maybe Word32