Add comments for common functions

Author: fendor

hie-plugin-api/Haskell/Ide/Engine/Cradle.hs

@@ -2,6 +2,10 @@ module Haskell.Ide.Engine.Cradle (findLocalCradle) where
 
 import HIE.Bios as BIOS
 
+-- | Find the cradle responsible for a filepath.
+-- If an explicit configuration is given, use it, otherwise
+-- try to guess a cradle based on certain heuristics, such as
+-- existence of stack.yaml and cabal.project.
 findLocalCradle :: FilePath -> IO Cradle
 findLocalCradle fp = do
   -- Get the cabal directory from the cradle

hie-plugin-api/Haskell/Ide/Engine/Ghc.hs

@@ -144,7 +144,9 @@ captureDiagnostics rfm action = do
       -- will be treated with the same severity of type errors. In order to offer a more useful
       -- experience, we make sure warnings are always reported as warnings by setting -Wwarn
       unsetWErr df = unSetGeneralFlag' Opt_WarnIsError (emptyFatalWarningFlags df)
+      -- previously, reported repeatedly about Missing Home Modules
       unsetMissingHomeModules = flip wopt_unset Opt_WarnMissingHomeModules
+      -- Preserve comments
       setRawTokenStream = setGeneralFlag' Opt_KeepRawTokenStream
 
       ghcErrRes msg = pure (mempty, [T.pack msg], Nothing)

hie-plugin-api/Haskell/Ide/Engine/GhcModuleCache.hs

@@ -1,7 +1,6 @@
 {-# LANGUAGE RankNTypes #-}
 {-# LANGUAGE ScopedTypeVariables #-}
 {-# LANGUAGE FlexibleContexts #-}
-{-# LANGUAGE TupleSections #-}
 
 module Haskell.Ide.Engine.GhcModuleCache where
 
@@ -118,11 +117,11 @@ instance Show CachedCradle where
 
 data GhcModuleCache = GhcModuleCache
   { cradleCache :: !(T.Trie CachedCradle)
-              -- ^ map from dirs to cradles
+              -- ^ map from filepaths to cradles
   , uriCaches  :: !UriCaches
   , currentCradle :: Maybe ([FilePath], BIOS.Cradle)
-              -- ^ The current cradle and which directories it is
-              -- responsible for
+              -- ^ The current cradle and which modules/filepaths it
+              -- is responsible for
   } deriving (Show)
 
 -- ---------------------------------------------------------------------

hie-plugin-api/Haskell/Ide/Engine/ModuleCache.hs

@@ -79,6 +79,10 @@ modifyCache f = do
 -- in either case
 runActionWithContext :: (MonadIde m, GHC.GhcMonad m, HasGhcModuleCache m, MonadBaseControl IO m)
                      => GHC.DynFlags -> Maybe FilePath -> m a -> m (IdeResult a)
+-- TODO: @fendor, this currently uses a IdeResult to provide either an error
+-- produced by `loadCradle` or the actual result of `m a`.
+-- We need a way to provide diagnostics from this action instead and report them back
+-- to the user.
 runActionWithContext _df Nothing action =
   -- Cradle with no additional flags
   -- dir <- liftIO $ getCurrentDirectory
@@ -92,7 +96,11 @@ runActionWithContext df (Just uri) action = do
     IdeResultOk () -> fmap IdeResultOk action
     IdeResultFail err -> return $ IdeResultFail err
 
-
+-- | Load a cradle based on the lookup result.
+-- This operation may take a very long time. If a new cradle is required,
+-- we now set up the GHC Session and load all modules.
+-- If the current cradle is reused, nothing needs to be done.
+-- If a cached cradle can be used, set the cradle as the current cradle.
 loadCradle :: (MonadIde m, HasGhcModuleCache m, GHC.GhcMonad m
               , MonadBaseControl IO m) => GHC.DynFlags -> LookupCradleResult -> m (IdeResult ())
 loadCradle _ ReuseCradle = do
@@ -115,8 +123,10 @@ loadCradle iniDynFlags (NewCradle fp) = do
   -- Now load the new cradle
   cradle <- liftIO $ findLocalCradle fp
   traceShowM cradle
+  -- set a new session
   liftIO (GHC.newHscEnv iniDynFlags) >>= GHC.setSession
   liftIO $ setCurrentDirectory (BIOS.cradleRootDir cradle)
+  -- initilise the session
   res <- gcatches
     (do
       withProgress "Initialising Cradle" NotCancellable (initializeCradle cradle)
@@ -146,17 +156,21 @@ loadCradle iniDynFlags (NewCradle fp) = do
           }
     ]
 
-
   case res of
     IdeResultOk () -> do
       setCurrentCradle cradle
       return (IdeResultOk ())
     err -> return err
  where
+  -- Simple helper function to detect, whether the given cradle is a stack cradle.
+  -- We need this, because we have to append the filepath, for which we are loading the cradle,
+  -- to the options because of the issue described in: https://github.com/mpickering/haskell-ide-engine/issues/10
+  -- tldr: stack does not actually load anything on initialisation, but rather on typechecking.
   isStackCradle :: BIOS.Cradle -> Bool
   isStackCradle c = BIOS.actionName (BIOS.cradleOptsProg c) == "stack"
 
-  -- initializeCradle ::
+  -- | Actually initialize the cradle.
+  -- Takes a function to report progress.
   initializeCradle :: GHC.GhcMonad m => BIOS.Cradle -> (Progress -> IO ()) -> m ()
   initializeCradle cradle f = do
     let msg = Just (toMessager f)
@@ -176,10 +190,12 @@ loadCradle iniDynFlags (NewCradle fp) = do
 
         targets <- BIOS.initSession opts'
         GHC.setTargets targets
-        -- Get the module graph using the function `getModuleGraph`
         mod_graph <- GHC.depanal [] True
         void $ GHC.load' GHC.LoadAllTargets msg mod_graph
 
+-- | Set the given cradle as our current context.
+-- Retrieves all filepaths this cradle is responsible for from the
+-- GHC.moduleGraph and caches them.
 setCurrentCradle :: (HasGhcModuleCache m, GHC.GhcMonad m) => BIOS.Cradle -> m ()
 setCurrentCradle cradle = do
     mg <- GHC.getModuleGraph
@@ -188,23 +204,21 @@ setCurrentCradle cradle = do
     ps' <- liftIO $ mapM canonicalizePath ps
     modifyCache (\s -> s { currentCradle = Just (ps', cradle) })
 
-
+-- | Cache the current cradle the modules it is responsible for.
 cacheCradle :: (HasGhcModuleCache m, GHC.GhcMonad m) => ([FilePath], BIOS.Cradle) -> m ()
 cacheCradle (ds, c) = do
   env <- GHC.getSession
   let cc = CachedCradle c env
       new_map = T.fromList (map (, cc) (map B.pack ds))
   modifyCache (\s -> s { cradleCache = T.unionWith (\a _ -> a) new_map (cradleCache s) })
 
--- | Get the Cradle that should be used for a given URI
---getCradle :: (GM.GmEnv m, MonadIO m, HasGhcModuleCache m, GM.GmLog m
---             , MonadBaseControl IO m, ExceptionMonad m, GM.GmOut m)
+-- | Get a cradle search result for a given filepath.
+-- Can be used to decide whether to load a new cradle or if the current one can be reused.
 getCradle :: (GHC.GhcMonad m, HasGhcModuleCache m)
          => FilePath -> m LookupCradleResult
 getCradle fp = do
   canon_fp <- liftIO $ canonicalizePath fp
-  mcache <- getModuleCache
-  return $ lookupCradle canon_fp mcache
+  lookupCradle canon_fp <$> getModuleCache
 
 ifCachedInfo :: (HasGhcModuleCache m, MonadIO m) => FilePath -> a -> (CachedInfo -> m a) -> m a
 ifCachedInfo fp def callback = do