Document indexHieFile

Author: wz1000

ghcide/src/Development/IDE/Core/Compile.hs

@@ -473,6 +473,32 @@ spliceExpresions Splices{..} =
         , DL.fromList $ map fst awSplices
         ]
 
+-- | In addition to indexing the `.hie` file, this function is reponsible for
+-- maintaining the IndexQueue state and notfiying the user about indexing
+-- progress.
+--
+-- We maintain a record of all pending index operations in theh 'indexPending'
+-- TVar When 'indexHieFile' is called, it must check to ensure that the file
+-- hasn't already be queued up for indexing. If it has, then we can just skip it
+--
+-- Otherwise, we record the current file as pending and write an indexing
+-- operation to the queue
+--
+-- When the indexing operation is picked up and executed by the worker thread,
+-- the first thing it does is ensure that a newer index for the same file
+-- hasn't been scheduled by looking at 'indexPending' If a newer index has been
+-- scheduled, we can safely skip this one
+--
+-- Otherwise, we start or continue a progress reporting session, telling it
+-- about progress so far and the current file we are attempting to index. Then
+-- we can go ahead and call in to hiedb to actually do the indexing operation
+--
+-- Once this completes, we have to update the IndexQueue state First, we
+-- must remove the just indexed file from 'indexPending' Then we check if
+-- 'indexPending' is now empty. In that case, we end the progress session and
+-- report the total number of file indexed. We also set the 'indexCompleted'
+-- TVar to 0 in order to set it up for a fresh indexing session. Otherwise, we
+-- can just increment the 'indexCompleted' TVar and exit.
 indexHieFile :: ShakeExtras -> ModSummary -> NormalizedFilePath -> Fingerprint -> Compat.HieFile -> IO ()
 indexHieFile se mod_summary srcPath hash hf = atomically $ do
   pending <- readTVar indexPending