Reintroduce type conventions: s/proj_type/pt/ s/cache/c/

2 files changed, 22 insertions, 7 deletions

diff --git a/lib/Distribution/Helper.hs b/lib/Distribution/Helper.hs
index 73c3438..2f9493e 100644
--- a/lib/Distribution/Helper.hs
+++ b/lib/Distribution/Helper.hs
@@ -30,6 +30,9 @@ Portability : POSIX
 -}
 
 module Distribution.Helper (
+  -- * Type Variable Naming Conventions
+  -- $type-conventions
+
   -- * Running Queries
     Query
   , runQuery
@@ -143,6 +146,18 @@ import Distribution.Verbosity (silent, deafening)
 --import Distribution.Package (packageName, packageVersion)
 import Distribution.Simple.GHC as GHC (configure)
 
+-- $type-conventions
+-- Throughout the API we use the following conventions for type variables:
+--
+-- * @pt@ stands for "project type", when instantiated is always of kind
+--   'ProjType'.
+--
+-- * @c@ stands for "cache". It is used internally to make the cache
+--   inaccessible for some parts of the implementation. Users of the API may
+--   ignore it. See the internal 'qeCacheRef' field accessor of 'QueryEnv' for
+--   details.
+
+
 -- | A lazy, cached, query against a package's Cabal configuration. Use
 -- 'runQuery' to execute it.
 newtype Query pt a = Query
diff --git a/src/CabalHelper/Compiletime/Types.hs b/src/CabalHelper/Compiletime/Types.hs
index 3c6ff73..5a19261 100644
--- a/src/CabalHelper/Compiletime/Types.hs
+++ b/src/CabalHelper/Compiletime/Types.hs
@@ -93,15 +93,15 @@ data DistDir (pt :: ProjType) where
 -- | Environment for running a 'Query' value. The real constructor is
 -- not exposed, use the 'mkQueryEnv' smart constructor instead. The field
 -- accessors are exported and may be used to override the defaults, see below.
-type QueryEnv (proj_type :: ProjType)
-    = QueryEnvI (QueryCache proj_type) proj_type
+type QueryEnv (pt :: ProjType)
+    = QueryEnvI QueryCache pt
 
-data QueryEnvI cache (proj_type :: ProjType) = QueryEnv
+data QueryEnvI c (pt :: ProjType) = QueryEnv
     { qeReadProcess
           :: !(Maybe FilePath -> FilePath -> [String] -> String -> IO String)
     -- ^ Field accessor for 'QueryEnv'. Function used to to start
     -- processes. Useful if you need to, for example, redirect standard error
-    -- output away from the user\'s terminal.
+    -- output of programs started by cabal-helper.
 
     , qePrograms     :: !Programs
     -- ^ Field accessor for 'QueryEnv'.
@@ -109,17 +109,17 @@ data QueryEnvI cache (proj_type :: ProjType) = QueryEnv
     , qeCompPrograms :: !CompPrograms
     -- ^ Field accessor for 'QueryEnv'.
 
-    , qeProjLoc      :: !(ProjLoc proj_type)
+    , qeProjLoc      :: !(ProjLoc pt)
     -- ^ Field accessor for 'QueryEnv'. Defines path to the project directory,
     -- i.e. a directory containing a @cabal.project@ file
 
-    , qeDistDir      :: !(DistDir proj_type)
+    , qeDistDir      :: !(DistDir pt)
     -- ^ Field accessor for 'QueryEnv'. Defines path to the @dist/@ or
     -- @dist-newstyle/@ directory, aka. /builddir/ in Cabal terminology.
 
-    , qeCacheRef     :: !(IORef cache)
     -- ^ Cache for query results, only accessible when type parameter @cache@ is
     -- instantiated and not forall quantified.
+    , qeCacheRef     :: !(IORef (c pt))
     }
 
 data QueryCache pt = QueryCache