From 25f632398da500308f593f9a95aadd247b5e8601 Mon Sep 17 00:00:00 2001
From: Felipe Lessa <felipe.lessa@gmail.com>
Date: Thu, 6 Sep 2012 10:35:55 -0300
Subject: [PATCH] Better top-level docs for internal modules.

---
 src/Database/Esqueleto/Internal/Language.hs | 13 +++++++++----
 src/Database/Esqueleto/Internal/Sql.hs      | 13 +++++++++----
 2 files changed, 18 insertions(+), 8 deletions(-)

diff --git a/src/Database/Esqueleto/Internal/Language.hs b/src/Database/Esqueleto/Internal/Language.hs
index 25ff05f..3e9fa9c 100644
--- a/src/Database/Esqueleto/Internal/Language.hs
+++ b/src/Database/Esqueleto/Internal/Language.hs
@@ -7,8 +7,12 @@
            , TypeFamilies
            , UndecidableInstances
  #-}
+-- | This is an internal module, anything exported by this module
+-- may change without a major version bump.  Please use only
+-- "Database.Esqueleto" if possible.
 module Database.Esqueleto.Internal.Language
-  ( Esqueleto(..)
+  ( -- * The pretty face
+    Esqueleto(..)
   , from
   , Value(..)
   , InnerJoin(..)
@@ -16,12 +20,13 @@ module Database.Esqueleto.Internal.Language
   , LeftOuterJoin(..)
   , RightOuterJoin(..)
   , FullOuterJoin(..)
-  , JoinKind(..)
-  , IsJoinKind(..)
   , OnClauseWithoutMatchingJoinException(..)
-  , PreprocessedFrom
   , OrderBy
   , Update
+    -- * The guts
+  , JoinKind(..)
+  , IsJoinKind(..)
+  , PreprocessedFrom
   , From
   , FromPreprocess
   ) where
diff --git a/src/Database/Esqueleto/Internal/Sql.hs b/src/Database/Esqueleto/Internal/Sql.hs
index 21957d6..fcbefdd 100644
--- a/src/Database/Esqueleto/Internal/Sql.hs
+++ b/src/Database/Esqueleto/Internal/Sql.hs
@@ -7,18 +7,23 @@
            , OverloadedStrings
            , UndecidableInstances
  #-}
+-- | This is an internal module, anything exported by this module
+-- may change without a major version bump.  Please use only
+-- "Database.Esqueleto" if possible.
 module Database.Esqueleto.Internal.Sql
-  ( SqlQuery
+  ( -- * The pretty face
+    SqlQuery
   , SqlExpr
   , select
   , selectSource
   , selectDistinct
   , selectDistinctSource
+  , delete
+  , update
+    -- * The guts
   , rawSelectSource
   , runSource
   , rawExecute
-  , delete
-  , update
   , toRawSql
   , Mode(..)
   , Escape
@@ -426,7 +431,7 @@ selectDistinct :: ( SqlSelect a r
 selectDistinct = selectDistinctSource >=> runSource
 
 
--- | Runs a 'C.Source' of rows.
+-- | (Internal) Run a 'C.Source' of rows.
 runSource :: MonadResourceBase m =>
              C.Source (C.ResourceT (SqlPersist m)) r
           -> SqlPersist m [r]