Merge pull request #91 from himura/fix-document

Fix document

README.md

@@ -10,11 +10,6 @@ This is an conduit based Twitter API library for Haskell, including Streaming AP
 
 Documentation is available in [hackage](http://hackage.haskell.org/package/twitter-conduit).
 
-## Usage ##
-
-    $ cabal update
-    $ cabal install twitter-conduit
-
 ## Quick Start ##
 
 For a runnable example, see [sample/simple.hs](https://github.com/himura/twitter-conduit/blob/master/sample/simple.hs).
@@ -24,19 +19,32 @@ You can find other various examples in [sample](https://github.com/himura/twitte
 
 ### Build ###
 
-If you would like to use cabal sandbox, prepare sandbox as below:
+#### Building with Cabal ####
 
 ~~~~
-$ cabal sandbox init
+$ cabal v2-build all
 ~~~~
 
-and then,
+#### Building with Stack ####
 
-~~~~
-$ cabal install --only-dependencies -fbuild-samples
-$ cabal configure -fbuild-samples
-$ cabal build
-~~~~
+To build with Stack, you should create top-level `stack.yaml` file first.
+An example of `stack.yaml` is like below:
+
+```.yaml
+resolver: lts-18.12
+packages:
+- .
+- sample
+extra-deps:
+- twitter-types-0.11.0
+- twitter-types-lens-0.11.0
+```
+
+then, run stack.
+
+```
+$ stack build
+```
 
 ### Run ###
 

Web/Twitter/Conduit.hs

@@ -13,6 +13,18 @@ module Web.Twitter.Conduit (
     -- * How to use this library
     -- $howto
 
+    -- ** Authentication
+    -- $auth
+
+    -- ** How to call API
+    -- $call
+
+    -- *** How to specify API parameters
+    -- $parameter
+
+    -- *** Conduit API: Recursive API call with changing cursor parameter
+    -- $conduit
+
     -- * Re-exports
     module Web.Twitter.Conduit.Api,
     module Web.Twitter.Conduit.Cursor,
@@ -80,16 +92,21 @@ import qualified Data.Text.IO as T
 -- and <http://hackage.haskell.org/package/conduit conduit>.
 -- All of following examples import modules as below:
 --
--- > {\-# LANGUAGE OverloadedStrings #-\}
--- >
--- > import Web.Twitter.Conduit
--- > import Web.Twitter.Types.Lens
--- > import Data.Conduit
--- > import qualified Data.Conduit.List as CL
--- > import qualified Data.Text as T
--- > import qualified Data.Text.IO as T
--- > import Control.Monad.IO.Class
--- > import Control.Lens
+-- @
+-- {\-# LANGUAGE OverloadedLabels #-\}
+-- {\-# LANGUAGE OverloadedStrings #-\}
+--
+-- import Web.Twitter.Conduit
+-- import Web.Twitter.Types.Lens
+-- import Data.Conduit
+-- import qualified Data.Conduit.List as CL
+-- import qualified Data.Text as T
+-- import qualified Data.Text.IO as T
+-- import Control.Monad.IO.Class
+-- import Control.Lens
+-- @
+
+-- $auth
 --
 -- First, you should obtain consumer token and secret from <https://apps.twitter.com/ Twitter>,
 -- and prepare 'OAuth' variables as follows:
@@ -132,15 +149,19 @@ import qualified Data.Text.IO as T
 --
 -- Or, simply as follows:
 --
--- > twInfo = setCredential tokens credential def
+-- @
+-- twInfo = 'setCredential' tokens credential 'def'
+-- @
+
+-- $call
 --
 -- Twitter API requests are performed by 'call' function.
 -- For example, <https://dev.twitter.com/docs/api/1.1/get/statuses/home_timeline GET statuses/home_timeline>
 -- could be obtained by:
 --
 -- @
 -- mgr \<- 'newManager' 'tlsManagerSettings'
--- timeline \<- 'call' twInfo mgr 'homeTimeline'
+-- timeline \<- 'call' twInfo mgr 'statusesHomeTimeline'
 -- @
 --
 -- The response of 'call' function is wrapped by the suitable type of
@@ -153,8 +174,47 @@ import qualified Data.Text.IO as T
 -- includes 20 tweets, and you can change the number of tweets by the /count/ parameter.
 --
 -- @
--- timeline \<- 'call' twInfo mgr '$' 'homeTimeline' '&' #count '?~' 200
+-- timeline \<- 'call' twInfo mgr '$' 'statusesHomeTimeline' '&' #count '?~' 200
 -- @
+
+-- $parameter
+--
+-- The parameters which can be specified for this API, is able to be obtained from type parameters of APIRequest.
+-- For example,
+--
+-- @
+-- 'statusesHomeTimeline' ::
+--     'APIRequest' 'StatusesHomeTimeline' ['Web.Twitter.Types.Status']
+-- @
+--
+-- - The 2nd type parameter of 'APIRequest' represents acceptable parameters in this API request.
+-- - The 3nd type parameter of 'APIRequest' denotes a return type of this API request.
+--
+-- The 2nd type parameter of 'statusesHomeTimeline' is 'StatusesHomeTimeline' defined as below:
+--
+-- @
+-- type StatusesHomeTimeline =
+--     '[ "count" ':= Integer
+--      , "since_id" ':= Integer
+--      , "max_id" ':= Integer
+--      , "trim_user" ':= Bool
+--      , "exclude_replies" ':= Bool
+--      , "contributor_details" ':= Bool
+--      , "include_entities" ':= Bool
+--      , "tweet_mode" ':= TweetMode
+--      ]
+-- @
+--
+-- Each element of list represents the name and type of API parameters.
+-- You can specify those parameter with OverloadedLabels extension.
+-- In the above example, it shows that 'statusesHomeTimeline' API supports "tweet_mode" parameter with 'TweetMode' type, so
+-- you can specify "tweet_mode" parameter as:
+--
+-- @
+-- 'statusesHomeTimeline' & #tweet_mode ?~ 'Extended'
+-- @
+
+-- $conduit
 --
 -- If you need more statuses, you can obtain those with multiple API requests.
 -- This library provides the wrapper for multiple requests with conduit interfaces.
@@ -163,24 +223,31 @@ import qualified Data.Text.IO as T
 -- or use the conduit wrapper 'sourceWithCursor' as below:
 --
 -- @
--- friends \<- 'sourceWithCursor' twInfo mgr ('friendsList' ('ScreenNameParam' \"thimura\") '&' #count '?~' 200) '$$' 'CL.consume'
+-- friends \<-
+--     'runConduit' $
+--         'sourceWithMaxId' twInfo mgr ('friendsList' ('ScreenNameParam' \"thimura\") '&' #count '?~' 200)
+--             '.|' 'CL.consume'
 -- @
 --
 -- Statuses APIs, for instance, 'homeTimeline', are also wrapped by 'sourceWithMaxId'.
 --
--- For example, you can print 1000 tweets from your home timeline, as below:
+-- For example, you can print 60 tweets from your home timeline, as below:
 --
 -- @
 -- main :: IO ()
 -- main = do
 --     mgr \<- 'newManager' 'tlsManagerSettings'
---     'sourceWithMaxId' twInfo mgr 'homeTimeline'
---         $= CL.isolate 60
---         $$ CL.mapM_ $ \\status -> liftIO $ do
---             T.putStrLn $ T.concat [ T.pack . show $ status ^. statusId
---                                   , \": \"
---                                   , status ^. statusUser . userScreenName
---                                   , \": \"
---                                   , status ^. statusText
---                                   ]
+--     'runConduit' $ 'sourceWithMaxId' twInfo mgr 'homeTimeline'
+--         '.|' CL.isolate 60
+--         '.|' CL.mapM_
+--             (\\status -> do
+--                  T.putStrLn $
+--                      T.concat
+--                          [ T.pack . show $ status ^. statusId
+--                          , \": \"
+--                          , status ^. statusUser . userScreenName
+--                          , \": \"
+--                          , status ^. statusText
+--                          ]
+--             )
 -- @