Add lots of comments

Author: pepeiborra

src/Ide/Plugin/ImportLens.hs

@@ -1,3 +1,4 @@
+{-# LANGUAGE ViewPatterns #-}
 {-# LANGUAGE DeriveAnyClass        #-}
 {-# LANGUAGE DeriveGeneric         #-}
 {-# LANGUAGE DerivingStrategies    #-}
@@ -22,13 +23,11 @@ import qualified Data.Text                      as T
 import           Development.IDE.Core.RuleTypes (GhcSessionDeps (GhcSessionDeps),
                                                  TcModuleResult (tmrModule),
                                                  TypeCheck (TypeCheck))
-import           Development.IDE.Core.Service   (IdeState, runAction)
 import           Development.IDE.Core.Shake     (IdeAction, IdeState (..),
-                                                 runIdeAction, useWithStaleFast,
-                                                 use_)
+                                                 runIdeAction, useWithStaleFast)
 import           Development.IDE.GHC.Compat
 import           Development.IDE.GHC.Error      (realSpan, realSrcSpanToRange)
-import           Development.IDE.GHC.Util       (hscEnv, prettyPrint)
+import           Development.IDE.GHC.Util       (HscEnvEq, hscEnv, prettyPrint)
 import           GHC.Generics                   (Generic)
 import           Ide.Plugin
 import           Ide.Types
@@ -42,46 +41,64 @@ import           TcRnTypes                      (TcGblEnv (tcg_used_gres))
 importCommandId :: CommandId
 importCommandId = "ImportLensCommand"
 
+-- | The "main" function of a plugin
 descriptor :: PluginId -> PluginDescriptor
 descriptor plId = (defaultPluginDescriptor plId) {
+    -- This plugin provides code lenses
     pluginCodeLensProvider = Just provider,
+    -- This plugin provides a command handler
     pluginCommands = [ importLensCommand ]
 }
 
+-- | The command descriptor
 importLensCommand :: PluginCommand
 importLensCommand =
     PluginCommand importCommandId "Explicit import command" runImportCommand
 
+-- | The type of the parameters accepted by our command
 data ImportCommandParams = ImportCommandParams WorkspaceEdit
   deriving Generic
   deriving anyclass (FromJSON, ToJSON)
 
+-- | The actual command handler
 runImportCommand :: CommandFunction ImportCommandParams
 runImportCommand _lspFuncs _state (ImportCommandParams edit) = do
+    -- This command simply triggers a workspace edit!
     return (Right Null, Just (WorkspaceApplyEdit, ApplyWorkspaceEditParams edit))
 
--- For every implicit import statement,
--- return a code lens of the corresponding explicit import
--- Example. For the module below:
+-- | For every implicit import statement, return a code lens of the corresponding explicit import
+-- Example - for the module below:
 --
 -- > import Data.List
 -- >
 -- > f = intercalate " " . sortBy length
 --
--- the provider should produce one code lens:
+-- the provider should produce one code lens associated to the import statement:
 --
 -- > import Data.List (intercalate, sortBy)
-
 provider :: CodeLensProvider
-provider _lspFuncs state pId CodeLensParams{..}
-  | TextDocumentIdentifier{_uri} <- _textDocument
-  , Just nfp <- uriToNormalizedFilePath $ toNormalizedUri _uri
+provider _lspFuncs          -- LSP functions, not used
+         state              -- ghcide state, used to retrieve typechecking artifacts
+         pId                -- plugin Id
+         CodeLensParams{_textDocument = TextDocumentIdentifier{_uri}}
+  -- VSCode uses URIs instead of file paths
+  -- haskell-lsp provides conversion functions
+  | Just nfp <- uriToNormalizedFilePath $ toNormalizedUri _uri
   = do
-    Just (tmr, _) <- runIde state $ useWithStaleFast TypeCheck nfp
-    hsc <- hscEnv <$> runAction "importLens" state (use_ GhcSessionDeps nfp)
-    (imports, mbMinImports) <- extractMinimalImports hsc (tmrModule tmr)
+    -- Get the typechecking artifacts from the module, even if they are stale.
+    -- This is for responsiveness - we don't want our code lenses to vanish
+    -- just because there is a type error unrelated to the moduel imports.
+    -- However, if the user edits the imports while the module does not typecheck,
+    -- our code lenses will get out of sync
+    tmr <- runIde state $ useWithStaleFast TypeCheck nfp
+    -- We also need a GHC session with all the dependencies
+    hsc <- runIde state $ useWithStaleFast GhcSessionDeps nfp
+    -- Use the GHC api to extract the "minimal" imports
+    (imports, mbMinImports) <- extractMinimalImports hsc tmr
 
     case mbMinImports of
+        -- Implement the provider logic:
+        -- for every import, if it's lacking a explicit list, generate a code lens
         Just minImports -> do
             let minImportsMap =
                     Map.fromList [ (srcSpanStart l, i) | L l i <- minImports ]
@@ -93,41 +110,63 @@ provider _lspFuncs state pId CodeLensParams{..}
   | otherwise
   = return $ Right (List [])
 
-extractMinimalImports :: HscEnv -> TypecheckedModule -> IO ([LImportDecl GhcRn], Maybe [LImportDecl GhcRn])
-extractMinimalImports hsc TypecheckedModule{..} = do
+-- | Use the ghc api to extract a minimal, explicit set of imports for this module
+extractMinimalImports
+  :: Maybe (HscEnvEq, a)
+  -> Maybe (TcModuleResult, b)
+  -> IO ([LImportDecl GhcRn], Maybe [LImportDecl GhcRn])
+extractMinimalImports (Just (hsc, _)) (Just (tmrModule -> TypecheckedModule{..}, _)) = do
+    -- extract the original imports and the typechecking environment
     let (tcEnv,_) = tm_internals_
         Just (_, imports, _, _) = tm_renamed_source
         ParsedModule{ pm_parsed_source = L loc _} = tm_parsed_module
+        span = fromMaybe (error "expected real") $ realSpan loc
 
+    -- GHC is secretly full of mutable state
     gblElts <- readIORef (tcg_used_gres tcEnv)
+
+    -- call findImportUsage does exactly what we need
+    -- GHC is full of treats like this
     let usage = findImportUsage imports gblElts
-        span = fromMaybe (error "expected real") $ realSpan loc
-    (_, minimalImports) <- initTcWithGbl hsc tcEnv span $ getMinimalImports usage
+    (_, minimalImports) <- initTcWithGbl (hscEnv hsc) tcEnv span $ getMinimalImports usage
+
+    -- return both the original imports and the computed minimal ones
     return (imports, minimalImports)
 
+extractMinimalImports _ _ = return ([], Nothing)
+
+-- | Given an import declaration, generate a code lens unless it has an explicit import list
 generateLens :: PluginId -> Uri -> Map SrcLoc (ImportDecl GhcRn) -> LImportDecl GhcRn -> IO (Maybe CodeLens)
 generateLens pId uri minImports (L src imp)
+  -- Explicit import list case
   | ImportDecl{ideclHiding = Just (False,_)} <- imp
   = return Nothing
+  -- No explicit import list
   | RealSrcSpan l <- src
   , Just explicit <- Map.lookup (srcSpanStart src) minImports
   , L _ mn <- ideclName imp
+  -- (almost) no one wants to see an explicit import list for Prelude
   , mn /= moduleName pRELUDE
   = do
+        -- The title of the command is just the minimal explicit import decl
     let title = T.pack $ prettyPrint explicit
-        commandArgs = Nothing
-    c <- mkLspCommand pId importCommandId title commandArgs
-    let _range :: Range = realSrcSpanToRange l
+        -- the range of the code lens is the span of the original import decl
+        _range :: Range = realSrcSpanToRange l
+        -- the code lens has no extra data
         _xdata = Nothing
+        -- an edit that replaces the whole declaration with the explicit one
         edit = WorkspaceEdit (Just editsMap) Nothing
         editsMap = HashMap.fromList [(uri, List [importEdit])]
         importEdit = TextEdit _range title
-        args = ImportCommandParams edit
-        _arguments = Just (List [toJSON args])
-        _command = Just (c :: Command){_arguments}
+        -- the command argument is simply the edit
+        _arguments = Just [toJSON $ ImportCommandParams edit]
+    -- create the command
+    _command <- Just <$> mkLspCommand pId importCommandId title _arguments
+    -- create and return the code lens
     return $ Just CodeLens{..}
   | otherwise
   = return Nothing
 
+-- | A helper to run ide actions
 runIde :: IdeState -> IdeAction a -> IO a
 runIde state = runIdeAction "importLens" (shakeExtras state)