Commits

Bryan O'Sullivan committed edf8031

Improve documentation here and there.

  • Participants
  • Parent commits c099150

Comments (0)

Files changed (3)

src/Network/Riak/Basic.hs

 getServerInfo :: Connection -> IO ServerInfo
 getServerInfo conn = exchange conn Req.getServerInfo
 
--- | Retrieve up a value.  This may return multiple conflicting
--- siblings.  Choosing among them is your responsibility.
+-- | Retrieve a value.  This may return multiple conflicting siblings.
+-- Choosing among them is your responsibility.
 get :: Connection -> T.Bucket -> T.Key -> R
     -> IO (Maybe (Seq.Seq Content, VClock))
 get conn bucket key r = Resp.get <$> exchangeMaybe conn (Req.get bucket key r)
 -- | Store a single value.  This may return multiple conflicting
 -- siblings.  Choosing among them, and storing a new value, is your
 -- responsibility.
+--
+-- You should /only/ supply 'Nothing' as a 'T.VClock' if you are sure
+-- that the given bucket+key combination does not already exist.  If
+-- you omit a 'T.VClock' but the bucket+key /does/ exist, your value
+-- will not be stored.
 put :: Connection -> T.Bucket -> T.Key -> Maybe T.VClock
     -> Content -> W -> DW
     -> IO (Seq.Seq Content, VClock)
 
 -- | Store a single value, without the possibility of conflict
 -- resolution.
+--
+-- You should /only/ supply 'Nothing' as a 'T.VClock' if you are sure
+-- that the given bucket+key combination does not already exist.  If
+-- you omit a 'T.VClock' but the bucket+key /does/ exist, your value
+-- will not be stored, and you will not be notified.
 put_ :: Connection -> T.Bucket -> T.Key -> Maybe T.VClock
      -> Content -> W -> DW
      -> IO ()

src/Network/Riak/JSON.hs

     toContent (J a) = V.toContent (toJSON a)
     {-# INLINE toContent #-}
 
+-- | Retrieve a value.  This may return multiple conflicting siblings.
+-- Choosing among them is your responsibility.
 get :: (FromJSON c, ToJSON c) => Connection -> Bucket -> Key -> R
     -> IO (Maybe ([c], VClock))
 get conn bucket key r = fmap convert <$> V.get conn bucket key r
     -> IO [Maybe ([c], VClock)]
 getMany conn bucket ks r = map (fmap convert) <$> V.getMany conn bucket ks r
 
+-- | Store a single value.  This may return multiple conflicting
+-- siblings.  Choosing among them, and storing a new value, is your
+-- responsibility.
+--
+-- You should /only/ supply 'Nothing' as a 'T.VClock' if you are sure
+-- that the given bucket+key combination does not already exist.  If
+-- you omit a 'T.VClock' but the bucket+key /does/ exist, your value
+-- will not be stored.
 put :: (FromJSON c, ToJSON c) =>
        Connection -> Bucket -> Key -> Maybe VClock -> c
     -> W -> DW -> IO ([c], VClock)
 put conn bucket key mvclock val w dw =
     convert <$> V.put conn bucket key mvclock (json val) w dw
 
+-- | Store a single value, without the possibility of conflict
+-- resolution.
+--
+-- You should /only/ supply 'Nothing' as a 'T.VClock' if you are sure
+-- that the given bucket+key combination does not already exist.  If
+-- you omit a 'T.VClock' but the bucket+key /does/ exist, your value
+-- will not be stored, and you will not be notified.
 put_ :: (FromJSON c, ToJSON c) =>
        Connection -> Bucket -> Key -> Maybe VClock -> c
     -> W -> DW -> IO ()
 put_ conn bucket key mvclock val w dw =
     V.put_ conn bucket key mvclock (json val) w dw
 
+-- | Store many values.  This may return multiple conflicting siblings
+-- for each value stored.  Choosing among them, and storing a new
+-- value in each case, is your responsibility.
+--
+-- You should /only/ supply 'Nothing' as a 'T.VClock' if you are sure
+-- that the given bucket+key combination does not already exist.  If
+-- you omit a 'T.VClock' but the bucket+key /does/ exist, your value
+-- will not be stored.
 putMany :: (FromJSON c, ToJSON c) =>
-       Connection -> Bucket -> [(Key, Maybe VClock, c)]
-    -> W -> DW -> IO [([c], VClock)]
+           Connection -> Bucket -> [(Key, Maybe VClock, c)]
+        -> W -> DW -> IO [([c], VClock)]
 putMany conn bucket puts w dw =
     map convert <$> V.putMany conn bucket (map f puts) w dw
   where f (k,v,c) = (k,v,json c)
 
+-- | Store many values, without the possibility of conflict
+-- resolution.
+--
+-- You should /only/ supply 'Nothing' as a 'T.VClock' if you are sure
+-- that the given bucket+key combination does not already exist.  If
+-- you omit a 'T.VClock' but the bucket+key /does/ exist, your value
+-- will not be stored, and you will not be notified.
 putMany_ :: (FromJSON c, ToJSON c) =>
             Connection -> Bucket -> [(Key, Maybe VClock, c)]
          -> W -> DW -> IO ()

src/Network/Riak/Value.hs

-{-# LANGUAGE GeneralizedNewtypeDeriving, OverloadedStrings, RecordWildCards, StandaloneDeriving #-}
+{-# LANGUAGE GeneralizedNewtypeDeriving, OverloadedStrings, RecordWildCards,
+    StandaloneDeriving #-}
 
 -- |
 -- Module:      Network.Riak.Value
 
 deriving instance (IsContent a) => IsContent (ResolvableMonoid a)
 
+-- | Store a single value.  This may return multiple conflicting
+-- siblings.  Choosing among them, and storing a new value, is your
+-- responsibility.
+--
+-- You should /only/ supply 'Nothing' as a 'T.VClock' if you are sure
+-- that the given bucket+key combination does not already exist.  If
+-- you omit a 'T.VClock' but the bucket+key /does/ exist, your value
+-- will not be stored.
 put :: (IsContent c) => Connection -> Bucket -> Key -> Maybe VClock -> c
     -> W -> DW -> IO ([c], VClock)
 put conn bucket key mvclock val w dw =
   putResp =<< exchange conn
               (Req.put bucket key mvclock (toContent val) w dw True)
 
+-- | Store many values.  This may return multiple conflicting siblings
+-- for each value stored.  Choosing among them, and storing a new
+-- value in each case, is your responsibility.
+--
+-- You should /only/ supply 'Nothing' as a 'T.VClock' if you are sure
+-- that the given bucket+key combination does not already exist.  If
+-- you omit a 'T.VClock' but the bucket+key /does/ exist, your value
+-- will not be stored.
 putMany :: (IsContent c) => Connection -> Bucket -> [(Key, Maybe VClock, c)]
         -> W -> DW -> IO [([c], VClock)]
 putMany conn b puts w dw =
       c <- convert content
       return (c, VClock s)
 
+-- | Store a single value, without the possibility of conflict
+-- resolution.
+--
+-- You should /only/ supply 'Nothing' as a 'T.VClock' if you are sure
+-- that the given bucket+key combination does not already exist.  If
+-- you omit a 'T.VClock' but the bucket+key /does/ exist, your value
+-- will not be stored, and you will not be notified.
 put_ :: (IsContent c) => Connection -> Bucket -> Key -> Maybe VClock -> c
     -> W -> DW -> IO ()
 put_ conn bucket key mvclock val w dw =
   exchange_ conn (Req.put bucket key mvclock (toContent val) w dw False)
 
+-- | Store many values, without the possibility of conflict
+-- resolution.
+--
+-- You should /only/ supply 'Nothing' as a 'T.VClock' if you are sure
+-- that the given bucket+key combination does not already exist.  If
+-- you omit a 'T.VClock' but the bucket+key /does/ exist, your value
+-- will not be stored, and you will not be notified.
 putMany_ :: (IsContent c) => Connection -> Bucket -> [(Key, Maybe VClock, c)]
          -> W -> DW -> IO ()
 putMany_ conn b puts w dw =
   pipeline_ conn . map (\(k,v,c) -> Req.put b k v (toContent c) w dw False) $ puts
 
+-- | Retrieve a value.  This may return multiple conflicting siblings.
+-- Choosing among them is your responsibility.
 get :: (IsContent c) => Connection -> Bucket -> Key -> R
     -> IO (Maybe ([c], VClock))
 get conn bucket key r = getResp =<< exchangeMaybe conn (Req.get bucket key r)