From 9150f4f13524e47749fedfd6e2cfeffdb3278323 Mon Sep 17 00:00:00 2001
From: Nikita Volkov <nikita.y.volkov@mail.ru>
Date: Sun, 28 Apr 2024 09:37:53 +0300
Subject: [PATCH] Add docs

---
 library/Hasql/Pipeline/Core.hs | 19 +++++++++++++++++++
 library/Hasql/Session/Core.hs  |  4 +++-
 2 files changed, 22 insertions(+), 1 deletion(-)

diff --git a/library/Hasql/Pipeline/Core.hs b/library/Hasql/Pipeline/Core.hs
index 4c76ae4..d12e74d 100644
--- a/library/Hasql/Pipeline/Core.hs
+++ b/library/Hasql/Pipeline/Core.hs
@@ -54,6 +54,23 @@ run (Pipeline sendQueriesInIO) connection registry integerDatetimes = do
         True -> pure ()
         False -> ExceptT (Left . PipelineError . ClientError <$> Pq.errorMessage connection)
 
+-- |
+-- Abstraction over the pipelining mode of execution of queries.
+--
+-- It allows you to issue multiple queries to the server in much fewer network transactions.
+-- If the amounts of sent and received data do not surpass the buffer sizes it will be just a single roundtrip.
+-- Usually the buffer size is 8KB.
+--
+-- This execution mode is much more efficient than running queries directly from 'Hasql.Session.Session', because in session every statement execution involves a dedicated network roundtrip.
+-- An obvious question rises then: why not execute all queries like that?
+--
+-- In situations where the parameters depend on the result of another query it is impossible to execute them in parallel, because the client needs to receive the results of one query before sending the request to execute the next query.
+-- This reasoning is essentially the same as the one for the difference between 'Applicative' and 'Monad'.
+-- That\'s why 'Pipeline' does not have the 'Monad' instance.
+--
+-- To execute 'Pipeline' lift it into 'Session' via 'Hasql.Session.pipeline'.
+--
+-- __Attention__: using this feature requires \"libpq\" of version >14.
 newtype Pipeline a
   = Pipeline
       ( Pq.Connection ->
@@ -79,6 +96,8 @@ instance Applicative Pipeline where
             Right rRecv ->
               Right (liftA2 (<*>) lRecv rRecv)
 
+-- |
+-- Execute a statement in pipelining mode.
 statement :: params -> Statement.Statement params result -> Pipeline result
 statement params (Statement.Statement sql (Encoders.Params encoder) (Decoders.Result decoder) preparable) =
   Pipeline run
diff --git a/library/Hasql/Session/Core.hs b/library/Hasql/Session/Core.hs
index 8a8d381..0e5d139 100644
--- a/library/Hasql/Session/Core.hs
+++ b/library/Hasql/Session/Core.hs
@@ -46,7 +46,7 @@ sql sql =
       Decoders.Results.single Decoders.Result.noResult
 
 -- |
--- Parameters and a specification of a parametric single-statement query to apply them to.
+-- Execute a statement by providing parameters to it.
 statement :: params -> Statement.Statement params result -> Session result
 statement input (Statement.Statement template (Encoders.Params paramsEncoder) (Decoders.Result decoder) preparable) =
   Session
@@ -60,6 +60,8 @@ statement input (Statement.Statement template (Encoders.Params paramsEncoder) (D
           r2 <- IO.getResults pqConnection integerDatetimes decoder
           return $ r1 *> r2
 
+-- |
+-- Execute a pipeline.
 pipeline :: Pipeline.Pipeline result -> Session result
 pipeline pipeline =
   Session $ ReaderT \(Connection.Connection pqConnectionRef integerDatetimes registry) ->