Merge pull request #1224 from fendor/document-package

Add Documentation for Package Plugin

Author: fendor

src/Haskell/Ide/Engine/Plugin/Package.hs

@@ -64,14 +64,29 @@ packageDescriptor plId = PluginDescriptor
   }
 
 data AddParams = AddParams
-  { rootDirParam   :: FilePath -- ^ The root directory.
-  , fileParam      :: FilePath -- ^ A path to a module inside the
-                               -- library/executable/test-suite you want to
-                               -- add the package to.
-  , packageParam   :: T.Text   -- ^ The name of the package to add.
+  { rootDirParam   :: FilePath   -- ^ The root directory.
+  , fileParam      :: ModulePath -- ^ A path to a module inside the
+                                 -- library/executable/test-suite you want to
+                                 -- add the package to. May be a realtive oir
+                                 -- absolute path, thus, must be normalised.
+  , packageParam   :: Package    -- ^ The name of the package to add.
   }
   deriving (Eq, Show, Read, Generic, ToJSON, FromJSON)
 
+-- | FilePath to a cabal package description file.
+type CabalFilePath = FilePath
+-- | FilePath to a package.yaml package description file.
+type PackageYamlFilePath = FilePath
+-- | FilePath to a module within the project.
+-- May be used to establish what component the dependency shall be added to.
+type ModulePath = FilePath
+-- | Name of the Package to add.
+type Package = T.Text
+
+-- | Add a package to the project's dependencies.
+-- May fail if no project dependency specification can be found.
+-- Supported are `*.cabal` and `package.yaml` specifications.
+-- Moreover, may fail with an IOException in case of a filesystem problem.
 addCmd :: CommandFunc AddParams J.WorkspaceEdit
 addCmd = CmdSync $ \(AddParams rootDir modulePath pkg) -> do
 
@@ -83,30 +98,49 @@ addCmd = CmdSync $ \(AddParams rootDir modulePath pkg) -> do
       absFp <- liftIO $ canonicalizePath relFp
       let relModulePath = makeRelative (takeDirectory absFp) modulePath
 
-      liftToGhc $ editCabalPackage absFp relModulePath (T.unpack pkg) fileMap
+      liftToGhc $ editCabalPackage absFp relModulePath pkg fileMap
     HpackPackage relFp -> do
       absFp <- liftIO $ canonicalizePath relFp
       let relModulePath = makeRelative (takeDirectory absFp) modulePath
       liftToGhc $ editHpackPackage absFp relModulePath pkg
     NoPackage -> return $ IdeResultFail (IdeError PluginError "No package.yaml or .cabal found" Null)
 
-data PackageType = CabalPackage FilePath
-                 | HpackPackage FilePath
-                 | NoPackage
-
+data PackageType = CabalPackage FilePath -- ^ Location of Cabal File.
+                 | HpackPackage FilePath -- ^ Location of `package.yaml`
+                 | NoPackage -- ^ No package format has been found.
+
+-- | Find the package type the project with the given root uses.
+-- Might have weird results if there is more than one cabal package specification
+-- in the root directory.
+-- The `package.yaml` is preferred in case both files are present.
+-- May fail with various IOException's, for example if the given
+-- directory does not exist, a Hardware Failure happens or
+-- the permissions deny it.
+-- However, normally this command should succeeed without any exceptions.
 findPackageType :: FilePath -> IO PackageType
 findPackageType rootDir = do
   files <- getDirectoryContents rootDir
+  -- Search for all files that have '.cabal' as a file ending,
+  -- since that is the format of the cabal file. May be more to one or zero.
   let mCabal = listToMaybe $ filter (isExtensionOf "cabal") files
 
   mHpack <- findFile [rootDir] "package.yaml"
 
   return $ fromMaybe NoPackage $ asum [HpackPackage <$> mHpack, CabalPackage <$> mCabal]
 
+-- | Edit a hpack package to add the given package to the package.yaml.
+--
 -- Currently does not preserve format.
 -- Keep an eye out on this other GSOC project!
 -- https://github.com/wisn/format-preserving-yaml
-editHpackPackage :: FilePath -> FilePath -> T.Text -> IdeM (IdeResult WorkspaceEdit)
+editHpackPackage :: PackageYamlFilePath -- ^ Path to the package.yaml file
+                                        -- containing the package description.
+                 -> ModulePath -- ^ Path to the module where the command has
+                               -- been issued in.
+                               -- Used to find out what component the
+                               -- dependency shall be added to.
+                 -> Package -- ^ Name of the package to add as a dependency.
+                 -> IdeM (IdeResult WorkspaceEdit)
 editHpackPackage fp modulePath pkgName = do
   contents <- liftIO $ B.readFile fp
 
@@ -186,9 +220,16 @@ editHpackPackage fp modulePath pkgName = do
     addDep (Array deps) = Array $ fromList (String pkgName:GHC.Exts.toList deps)
     addDep _            = error "Not an array in addDep"
 
-
--- | Takes a cabal file and a path to a module in the dependency you want to edit.
-editCabalPackage :: FilePath -> FilePath ->  String -> (FilePath -> FilePath) -> IdeM (IdeResult J.WorkspaceEdit)
+-- | Takes a cabal file and a path to a module in the project and a package name to add
+-- to the cabal file. Reverse file map is needed to find the correct file in the project.
+-- May fail with an IOException if the Cabal file is invalid.
+editCabalPackage :: CabalFilePath -- ^ Path to the cabal file to add the dependency to.
+                 -> ModulePath -- ^ Path to the module that wants to add the package.
+                               -- Used to find out what component the
+                               -- dependency shall be added to.
+                 -> Package -- ^ Name of the package added as a dependency.
+                 -> (FilePath -> FilePath) -- ^ Reverse File for computing file diffs.
+                 -> IdeM (IdeResult J.WorkspaceEdit)
 editCabalPackage file modulePath pkgName fileMap = do
 
   package <- liftIO $ readGenericPackageDescription normal file
@@ -204,7 +245,6 @@ editCabalPackage file modulePath pkgName fileMap = do
 
   IdeResultOk <$> makeAdditiveDiffResult file newContents fileMap
 
-
   where
 
     applyLens :: L.HasBuildInfo a => Lens' GenericPackageDescription [(b, CondTree v c a)]
@@ -218,7 +258,7 @@ editCabalPackage file modulePath pkgName fileMap = do
     updateTree = mapIfHasModule modulePath (addDep pkgName)
 
 
-    mapIfHasModule :: L.HasBuildInfo a => FilePath -> (a -> a) -> CondTree v c a -> CondTree v c a
+    mapIfHasModule :: L.HasBuildInfo a => ModulePath -> (a -> a) -> CondTree v c a -> CondTree v c a
     mapIfHasModule modFp f = mapTreeData g
       where g x
               | null (sourceDirs x) = f x
@@ -227,18 +267,26 @@ editCabalPackage file modulePath pkgName fileMap = do
             hasThisModule = any (`isPrefixOf` modFp) . sourceDirs
             sourceDirs x = x ^. L.buildInfo . L.hsSourceDirs
 
-    addDep :: L.HasBuildInfo a => String -> a -> a
+    -- | Add the given package name to the cabal file.
+    -- Package is appended to the dependency list.
+    addDep :: L.HasBuildInfo a => Package -> a -> a
     addDep dep x = L.buildInfo . L.targetBuildDepends .~ newDeps $ x
       where oldDeps = x ^. L.buildInfo . L.targetBuildDepends
             -- Add it to the bottom of the dependencies list
-            newDeps = oldDeps ++ [Dependency (mkPackageName dep) anyVersion]
+            -- TODO: we could sort the depencies and then insert it,
+            -- or insert it in order iff the list is already sorted.
+            newDeps = oldDeps ++ [Dependency (mkPackageName (T.unpack dep)) anyVersion]
 
+-- | Provide a code action to add a package to the local package.yaml or cabal file.
+-- Reads from diagnostics the unknown import module path and searches for it on Hoogle.
+-- If found, offer a code action to add the package to the local package description.
 codeActionProvider :: CodeActionProvider
 codeActionProvider plId docId _ context = do
   mRootDir <- getRootPath
   let J.List diags = context ^. J.diagnostics
       pkgs = mapMaybe getAddablePackages diags
 
+  -- Search for packages that define the given module.
   res <- mapM (bimapM return Hoogle.searchPackages) pkgs
   actions <- catMaybes <$> mapM (uncurry (mkAddPackageAction mRootDir)) (concatPkgs res)
 
@@ -247,7 +295,8 @@ codeActionProvider plId docId _ context = do
   where
     concatPkgs = concatMap (\(d, ts) -> map (d,) ts)
 
-    mkAddPackageAction :: Maybe FilePath -> J.Diagnostic -> T.Text -> IdeM (Maybe J.CodeAction)
+    -- | Create the Add Package Action with the given diagnostics and the found package name.
+    mkAddPackageAction :: Maybe FilePath -> J.Diagnostic -> Package -> IdeM (Maybe J.CodeAction)
     mkAddPackageAction mRootDir diag pkgName = case (mRootDir, J.uriToFilePath (docId ^. J.uri)) of
      (Just rootDir, Just docFp) -> do
        let title = "Add " <> pkgName <> " as a dependency"
@@ -256,18 +305,20 @@ codeActionProvider plId docId _ context = do
        return $ Just (J.CodeAction title (Just J.CodeActionQuickFix) (Just (J.List [diag])) Nothing (Just cmd))
      _ -> return Nothing
 
-    getAddablePackages :: J.Diagnostic -> Maybe (J.Diagnostic, T.Text)
+    getAddablePackages :: J.Diagnostic -> Maybe (J.Diagnostic, Package)
     getAddablePackages diag@(J.Diagnostic _ _ _ (Just "ghcmod") msg _) = (diag,) <$> extractModuleName msg
     getAddablePackages _ = Nothing
 
-extractModuleName :: T.Text -> Maybe T.Text
+-- | Extract a module name from an error message.
+extractModuleName :: T.Text -> Maybe Package
 extractModuleName msg
   | T.isPrefixOf "Could not find module " msg = Just $ T.tail $ T.init nameAndQuotes
   | T.isPrefixOf "Could not load module " msg = Just $ T.tail $ T.init nameAndQuotes
   | otherwise = Nothing
   where line = head $ T.lines msg
         nameAndQuotes = T.dropWhileEnd (/= '’') $ T.dropWhile (/= '‘') line
 
+-- Example error messages
 {- GHC 8.6.2 error message is
 
 "Could not load module \8216Data.Text\8217\n" ++