Better top-level docs for internal modules.

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

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]