From a8dd97354e9cd925fa3aab878b8f864106c69ccd Mon Sep 17 00:00:00 2001
From: Richard Zetterberg <richard.zetterberg@googlemail.com>
Date: Thu, 31 Dec 2015 17:10:18 +0100
Subject: [PATCH] Adds example usage of 'in_' operator

---
 src/Database/Esqueleto/Internal/Language.hs | 20 +++++++++++++++++++-
 1 file changed, 19 insertions(+), 1 deletion(-)

diff --git a/src/Database/Esqueleto/Internal/Language.hs b/src/Database/Esqueleto/Internal/Language.hs
index 51ffc8a..9b8a56c 100644
--- a/src/Database/Esqueleto/Internal/Language.hs
+++ b/src/Database/Esqueleto/Internal/Language.hs
@@ -456,7 +456,25 @@ class (Functor query, Applicative query, Monad query) =>
   -- /Since: 2.2.12/
   justList :: expr (ValueList typ) -> expr (ValueList (Maybe typ))
 
-  -- | @IN@ operator.
+  -- | @IN@ operator. For example if you want to select all @Person@s by a list
+  -- of IDs:
+  --
+  -- @
+  -- SELECT *
+  -- FROM Person
+  -- WHERE Person.id IN (?)
+  -- @
+  --
+  -- In @esqueleto@, we may write the same query above as:
+  --
+  -- @
+  -- select $
+  -- 'from' $ \\person -> do
+  -- 'where_' $ person '^.' PersonId `in_` 'valList' personIds
+  -- return person
+  -- @
+  --
+  -- Where @personIds@ is of type @[Key Person]@.
   in_ :: PersistField typ => expr (Value typ) -> expr (ValueList typ) -> expr (Value Bool)
 
   -- | @NOT IN@ operator.