Call useWithStale instead of useWithStaleFast when calling ParseCabal…

…Fields (#4294)

Add documentation about this choice

Co-authored-by: Michael Peyton Jones <me@michaelpj.com>

plugins/hls-cabal-plugin/src/Ide/Plugin/Cabal.hs

@@ -314,7 +314,9 @@ completion recorder ide _ complParams = do
   mVf <- lift $ getVirtualFile $ toNormalizedUri uri
   case (,) <$> mVf <*> uriToFilePath' uri of
     Just (cnts, path) -> do
-      mFields <- liftIO $ runIdeAction "cabal-plugin.fields" (shakeExtras ide) $ useWithStaleFast ParseCabalFields $ toNormalizedFilePath path
+      -- We decide on `useWithStale` here, since `useWithStaleFast` often leads to the wrong completions being suggested.
+      -- In case it fails, we still will get some completion results instead of an error.
+      mFields <- liftIO $ runAction "cabal-plugin.fields" ide $ useWithStale ParseCabalFields $ toNormalizedFilePath path
       case mFields of
         Nothing ->
           pure . InR $ InR Null
@@ -335,6 +337,9 @@ completion recorder ide _ complParams = do
         let completer = Completions.contextToCompleter ctx
         let completerData = CompleterTypes.CompleterData
               { getLatestGPD = do
+                -- We decide on useWithStaleFast here, since we mostly care about the file's meta information,
+                -- thus, a quick response gives us the desired result most of the time.
+                -- The `withStale` option is very important here, since we often call this rule with invalid cabal files.
                 mGPD <- runIdeAction "cabal-plugin.modulesCompleter.gpd" (shakeExtras ide) $ useWithStaleFast ParseCabalFile $ toNormalizedFilePath fp
                 pure $ fmap fst mGPD
               , cabalPrefixInfo = prefInfo