Commits

John Lenz committed 0d2bc38

Mostly minor style updates to the documentation

Comments (0)

Files changed (1)

src/Database/CouchDB/Enumerator.hs

 >
 >    -- Delete test database
 >    couchDeleteDb ""
-
-To work with different databases inside one monad just set empty database name:
-
-> runCouch "localhost" 5984 "test" $ do
->     couchPutDb "test"
->     rev <- couchPut "test/doc1" [] $ object [ "foo" .= (3 :: Int), 
->                                               "bar" .= ("abc" :: String) ]
-
 -}
 
 module Database.CouchDB.Enumerator(
     -- * Couch DB database API
     , couchPutDb
     , couchDeleteDb
+
     -- * Couch DB documents API
     , Path
     , Revision
     , couchPutRev
     , couchPut_
     , couchDelete
+
     -- * Couch DB views API
     , couchView
     , extractViewValue
+
     -- * Low-level API
     , couch
     , couch'
 --   until the manager is closed (http-enumerator will create more connections 
 --   if needed, it just keeps only one and closes the rest.)  See the Pool 
 --   section for more information.
+--
+--   To access more than one database, the dbname entry can be set to the
+--   empty string.
 data CouchConnection = CouchConnection {
       host      :: B.ByteString
     , port      :: Int
 -- | Represents a revision of a Couch DB Document.
 type Revision = T.Text
 
--- | Simplified version of 'couch''. Not pass 'HT.Status' and 
---   'HT.ResponseHeaders' to 'Iteratee'.
+-- | Simplified version of 'couch''.  
+--
+--   Response headers are ignored, and the response status is only used to
+--   detect for an error, in which case a 'CouchError' is sent down the
+--   'Iteratee'.
 couch :: MonadCouch m
       => HT.Method                  -- ^ Method
       -> Path                       -- ^ The dbname from the connection is 
 --   functions, but this function is needed for example to write and read 
 --   attachments that are not in JSON format.
 -- 
---   Runs action or throws 'CouchError'. 
+--   If CouchDB returns an error, the iteratee passed to this function is not
+--   called and instead a 'CouchError' is sent out the Iteratee returned from
+--   this function.
 couch' :: MonadCouch m
       => HT.Method                  -- ^ Method
       -> Path                       -- ^ The dbname from the connection is 
                                     --   prepended to this path. Just set empty 
                                     --   if you need access to many DBs.
-      -> HT.RequestHeaders
+      -> HT.RequestHeaders          -- ^ Headers
       -> HT.Query                   -- ^ Query arguments
       -> (HT.ResponseHeaders -> Iteratee B.ByteString m a)  
                                     -- ^ Function what returns Iteratee to  
 --  
 --   but catches 'CouchError' /412/.
 couchPutDb :: MonadCouch m => 
-       Path -- ^ Database name. Set non-empty only if you set empty path in 
-            --   'runCouch', 'withCouchConnection' or 'couch''. 
+       Path -- ^ If you passed a database name to 'withCouchConnection',
+            --   'runCouch', or 'CouchConnection', the path should be
+            --   the empty string.  If you passed the empty string to
+            --   'CouchConnection', then the dbname should be used here.
     -> m ()
 couchPutDb p = 
     catch (couchPut_ p [] $ A.object []) handler
     handler (CouchError (Just 412) _) = return ()
     handler e = throw e
 
--- | Delete database.
+-- | Delete a database.
 couchDeleteDb :: MonadCouch m => 
-        Path    -- ^ Database name. Set non-empty only if you set empty path in 
-                --   'runCouch', 'withCouchConnection' or 'couch''. 
-     -> m ()
+       Path -- ^ If you passed a database name to 'withCouchConnection',
+            --   'runCouch', or 'CouchConnection', the path should be
+            --   the empty string.  If you passed the empty string to
+            --   'CouchConnection', then the dbname should be used here.
+    -> m ()
 couchDeleteDb p = run_ $ couch HT.methodDelete p []
                                (yield () EOF) 
                                (H.RequestBodyBS B.empty)
 
--- | Get Revision of document. 
+-- | Get Revision of a document. 
 couchRev :: MonadCouch m => Path -> m Revision
 couchRev p = do
     v <- run_ $ couch' HT.methodHead p [] [] getEtag (H.RequestBodyBS B.empty)