Merge pull request #1549 from fendor/cradle-fix-haddock

Fix haddock documentation for Cradle.hs

Author: lukel97

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

@@ -52,23 +52,24 @@ findLocalCradle fp = do
     Nothing   -> cabalHelperCradle fp
   logm $ "Module \"" ++ fp ++ "\" is loaded by Cradle: " ++ show crdl
   return crdl
+
 -- | Check if the given cradle is a stack cradle.
 -- This might be used to determine the GHC version to use on the project.
--- If it is a stack-cradle, we have to use `stack path --compiler-exe`
+-- If it is a stack-cradle, we have to use @"stack path --compiler-exe"@
 -- otherwise we may ask `ghc` directly what version it is.
 isStackCradle :: Cradle -> Bool
 isStackCradle = (`elem` ["stack", "Cabal-Helper-Stack", "Cabal-Helper-Stack-None"])
   . BIOS.actionName
   . BIOS.cradleOptsProg
 
-  -- | Check if the given cradle is a cabal cradle.
+-- | Check if the given cradle is a cabal cradle.
 -- This might be used to determine the GHC version to use on the project.
--- If it is a stack-cradle, we have to use `stack path --compiler-exe`
--- otherwise we may ask `ghc` directly what version it is.
+-- If it is a stack-cradle, we have to use @"stack path --compiler-exe"@
+-- otherwise we may ask @ghc@ directly what version it is.
 isCabalCradle :: Cradle -> Bool
 isCabalCradle =
   (`elem`
-    ["cabal"
+    [ "cabal"
     , "Cabal-Helper-Cabal-V1"
     , "Cabal-Helper-Cabal-V2"
     , "Cabal-Helper-Cabal-V1-Dir"
@@ -81,10 +82,10 @@ isCabalCradle =
 
 -- | Execute @ghc@ that is based on the given cradle.
 -- Output must be a single line. If an error is raised, e.g. the command
--- failed, a @Nothing@ is returned.
+-- failed, a 'Nothing' is returned.
 -- The exact error is written to logs.
 --
--- E.g. for a stack cradle, we use `stack ghc` and for a cabal cradle
+-- E.g. for a stack cradle, we use @stack ghc@ and for a cabal cradle
 -- we are taking the @ghc@ that is on the path.
 execProjectGhc :: Cradle -> [String] -> IO (Maybe String)
 execProjectGhc crdl args = do
@@ -167,6 +168,8 @@ This guessing has no guarantees and may change at any time.
 === Example:
 
 Assume the following project structure:
+
+@
   /
   └── Foo/
       ├── Foo.cabal
@@ -178,28 +181,31 @@ Assume the following project structure:
           ├── B.cabal
           └── src/
               └── Lib2.hs
+@
 
-Assume the call @findCabalHelperEntryPoint "/Foo/B/src/Lib2.hs"@.
-We now want to know to which project "/Foo/B/src/Lib2.hs" belongs to
+Assume the call @findCabalHelperEntryPoint "\/Foo\/B\/src\/Lib2.hs"@.
+We now want to know to which project "\/Foo\/B\/src\/Lib2.hs" belongs to
 and what the projects root is. If we only do a naive search to find the
 first occurrence of either "B.cabal", "stack.yaml", "cabal.project"
 or "Foo.cabal", we might assume that the location  of "B.cabal" marks
-the project's root directory of which "/Foo/B/src/Lib2.hs" is part of.
+the project's root directory of which "\/Foo\/B\/src\/Lib2.hs" is part of.
 However, there is also a "cabal.project" and "stack.yaml" in the parent
-directory, which add the package "B" as a package.
-So, the compilation of the package "B", and the file "src/Lib2.hs" in it,
+directory, which add the package @B@ as a package.
+So, the compilation of the package @B@, and the file "src\/Lib2.hs" in it,
 does not only depend on the definitions in "B.cabal", but also
 on "stack.yaml" and "cabal.project".
-The project root is therefore "/Foo/".
+The project root is therefore "\/Foo\/".
 Only if there is no "stack.yaml" or "cabal.project" in any of the ancestor
 directories, it is safe to assume that "B.cabal" marks the root of the project.
 
 Thus:
+
 >>> findCabalHelperEntryPoint "/Foo/B/src/Lib2.hs
 Just (Ex (ProjLocStackYaml { plStackYaml = "/Foo/"}))
 
 or
->>> findCabalHelperEntryPoint "/Foo/B/src/Lib2.hs
+
+>>> findCabalHelperEntryPoint "/Foo/B/src/Lib2.hs"
 Just (Ex (ProjLocV2File { plProjectDirV2 = "/Foo/"}))
 
 In the given example, it is not guaranteed which project type is found,
@@ -340,6 +346,8 @@ required to load and compile the given file.
 === Mono-Repo
 
 Assume the project structure:
+
+@
   /
   └── Mono/
       ├── cabal.project
@@ -350,21 +358,24 @@ Assume the project structure:
       └── B/
           ├── B.cabal
           └── Exe.hs
+@
 
 Currently, Haskell IDE Engine needs to know on startup which GHC version is
 needed to compile the project. This information is needed to show warnings to
 the user if the GHC version on the project does not agree with the GHC version
 that was used to compile Haskell IDE Engine.
 
 Therefore, the function 'findLocalCradle' is invoked with a dummy FilePath,
-such as "/Mono/Lib.hs". Since there will be no package that contains this
+such as "\/Mono\/Lib.hs". Since there will be no package that contains this
 dummy FilePath, the result will be a None-cradle.
 
 Either
+
 >>> findLocalCradle "/Mono/Lib.hs"
 Cradle { cradleRootDir = "/Mono/", CradleAction { actionName = "Cabal-Helper-Stack-None", ..} }
 
-or:
+or
+
 >>> findLocalCradle "/Mono/Lib.hs"
 Cradle { cradleRootDir = "/Mono/", CradleAction { actionName = "Cabal-Helper-Cabal-V2-None", ..} }
 
@@ -374,8 +385,9 @@ a 'cabal' project.
 
 
 If we are trying to load the executable:
+
 >>> findLocalCradle "/Mono/B/Exe.hs"
-Cradle { cradleRootDir = "/Mono/B/", CradleAction { actionName = "Cabal-Helper-Cabal-V2", ..} }
+Cradle { cradleRootDir = "/Mono/", CradleAction { actionName = "Cabal-Helper-Cabal-V2", ..} }
 
 we will detect correctly the compiler options, by first finding the appropriate
 package, followed by traversing the units in the package and finding the
@@ -384,6 +396,8 @@ component that exposes the executable by FilePath.
 === No explicit executable folder
 
 Assume the project structure:
+
+@
   /
   └── Library/
       ├── cabal.project
@@ -392,18 +406,21 @@ Assume the project structure:
       └── src
           ├── Lib.hs
           └── Exe.hs
+@
 
 There are different dependencies for the library "Lib.hs" and the
-executable "Exe.hs". If we are trying to load the executable "src/Exe.hs"
+executable "Exe.hs". If we are trying to load the executable "src\/Exe.hs"
 we will correctly identify the executable unit, and correctly initialise
 dependencies of "exe:Library".
 It will be correct even if we load the unit "lib:Library" before
 the "exe:Library" because the unit "lib:Library" does not expose
-a module "Exe".
+a module @"Exe"@.
 
 === Sub package
 
 Assume the project structure:
+
+@
   /
   └── Repo/
       ├── cabal.project
@@ -414,12 +431,13 @@ Assume the project structure:
       └── SubRepo
           ├── SubRepo.cabal
           └── Lib2.hs
+@
 
-When we try to load "/Repo/SubRepo/Lib2.hs", we need to identify root
-of the project, which is "/Repo/" but set the root directory of the cradle
-responsible to load "/Repo/SubRepo/Lib2.hs" to "/Repo/SubRepo", since
+When we try to load "\/Repo\/SubRepo\/Lib2.hs", we need to identify root
+of the project, which is "\/Repo\/" but set the root directory of the cradle
+responsible to load "\/Repo\/SubRepo\/Lib2.hs" to "\/Repo\/SubRepo", since
 the compiler options obtained from Cabal-Helper are relative to the package
-source directory, which is "/Repo/SubRepo".
+source directory, which is "\/Repo\/SubRepo".
 
 -}
 cabalHelperCradle :: FilePath -> IO Cradle
@@ -492,60 +510,60 @@ cabalHelperCradle file = do
                                         fp
                                     }
                    }
-    where
 
-      -- | Fix occurrences of "-i." to "-i<cradle-root-dir>"
-      -- Flags obtained from cabal-helper are relative to the package
-      -- source directory. This is less resilient to using absolute paths,
-      -- thus, we fix it here.
-      fixImportDirs :: FilePath -> String -> String
-      fixImportDirs base_dir arg =
-        if "-i" `isPrefixOf` arg
-          then let dir = drop 2 arg
-          -- the flag "-i" has special meaning.
-          in if not (null dir) && isRelative dir then ("-i" ++ base_dir </> dir)
-                                    else arg
-          else arg
-
-      -- | Cradle Action to query for the ComponentOptions that are needed
-      -- to load the given FilePath.
-      -- This Function is not supposed to throw any exceptions and use
-      -- 'CradleLoadResult' to indicate errors.
-      cabalHelperAction :: Ex ProjLoc -- ^ Project location, can be used
-                                      -- to present error build-tool
-                                      -- agnostic error messages.
-                        -> QueryEnv v -- ^ Query Env created by 'mkQueryEnv'
-                                      -- with the appropriate 'distdir'
-                        -> Package v -- ^ Package this cradle is part for.
-                        -> FilePath -- ^ Root directory of the cradle
-                                    -- this action belongs to.
-                        -> FilePath -- ^ FilePath to load, expected to be an absolute path.
-                        -> IO (CradleLoadResult ComponentOptions)
-      cabalHelperAction proj env package root fp = do
-        -- Get all unit infos the given FilePath may belong to
-        let units = pUnits package
-        -- make the FilePath to load relative to the root of the cradle.
-        let relativeFp = makeRelative root fp
-        debugm $ "Relative Module FilePath: " ++ relativeFp
-        getComponent proj env (toList units) relativeFp
-          >>= \case
-            Right comp -> do
-              let fs' = getFlags comp
-              let fs = map (fixImportDirs root) fs'
-              let targets = getTargets comp relativeFp
-              let ghcOptions = fs ++ targets
-              debugm $ "Flags for \"" ++ fp ++ "\": " ++ show ghcOptions
-              debugm $ "Component Infos: " ++ show comp
-              return
-                $ CradleSuccess
-                  ComponentOptions { componentOptions = ghcOptions
-                                   , componentDependencies = []
-                                   }
-            Left err   -> return
-              $ CradleFail
-              $ CradleError
-                (ExitFailure 2)
-                err
+-- | Cradle Action to query for the ComponentOptions that are needed
+-- to load the given FilePath.
+-- This Function is not supposed to throw any exceptions and use
+-- 'CradleLoadResult' to indicate errors.
+cabalHelperAction :: Ex ProjLoc -- ^ Project location, can be used
+                                -- to present build-tool
+                                -- agnostic error messages.
+                  -> QueryEnv v -- ^ Query Env created by 'mkQueryEnv'
+                                -- with the appropriate 'distdir'
+                  -> Package v -- ^ Package this cradle is part for.
+                  -> FilePath -- ^ Root directory of the cradle
+                              -- this action belongs to.
+                  -> FilePath -- ^ FilePath to load, expected to be an absolute path.
+                  -> IO (CradleLoadResult ComponentOptions)
+cabalHelperAction proj env package root fp = do
+  -- Get all unit infos the given FilePath may belong to
+  let units = pUnits package
+  -- make the FilePath to load relative to the root of the cradle.
+  let relativeFp = makeRelative root fp
+  debugm $ "Relative Module FilePath: " ++ relativeFp
+  getComponent proj env (toList units) relativeFp
+    >>= \case
+      Right comp -> do
+        let fs' = getFlags comp
+        let fs = map (fixImportDirs root) fs'
+        let targets = getTargets comp relativeFp
+        let ghcOptions = fs ++ targets
+        debugm $ "Flags for \"" ++ fp ++ "\": " ++ show ghcOptions
+        debugm $ "Component Infos: " ++ show comp
+        return
+          $ CradleSuccess
+            ComponentOptions { componentOptions = ghcOptions
+                              , componentDependencies = []
+                              }
+      Left err   -> return
+        $ CradleFail
+        $ CradleError
+          (ExitFailure 2)
+          err
+
+-- | Fix occurrences of "-i." to "-i<cradle-root-dir>"
+-- Flags obtained from cabal-helper are relative to the package
+-- source directory. This is less resilient to using absolute paths,
+-- thus, we fix it here.
+fixImportDirs :: FilePath -> String -> String
+fixImportDirs base_dir arg =
+  if "-i" `isPrefixOf` arg
+    then let dir = drop 2 arg
+    -- the flag "-i" has special meaning.
+    in if not (null dir) && isRelative dir then ("-i" ++ base_dir </> dir)
+                              else arg
+    else arg
+
 
 -- | Get the component the given FilePath most likely belongs to.
 -- Lazily ask units whether the given FilePath is part of one of their
@@ -826,8 +844,8 @@ ancestors dir
   where
     subdir = takeDirectory dir
 
--- | Assuming a FilePath "src/Lib/Lib.hs" and a list of directories
--- such as ["src", "app"], returns either the given FilePath
+-- | Assuming a FilePath @"src\/Lib\/Lib.hs"@ and a list of directories
+-- such as @["src", "app"]@, returns either the given FilePath
 -- with a matching directory stripped away.
 -- If there are multiple matches, e.g. multiple directories are a prefix
 -- of the given FilePath, return the first match in the list.