From f272c24e0e5fca05d4d7883c2c8ee6810b0242d9 Mon Sep 17 00:00:00 2001
From: Fendor <power.walross@gmail.com>
Date: Wed, 23 Feb 2022 18:32:24 +0100
Subject: [PATCH] Document assumptions LocalUnpackedPackage fields

---
 .../src/Distribution/Client/ProjectConfig.hs    | 17 +++++++++++++++--
 .../Client/Types/PackageLocation.hs             | 11 ++++++++---
 2 files changed, 23 insertions(+), 5 deletions(-)

diff --git a/cabal-install/src/Distribution/Client/ProjectConfig.hs b/cabal-install/src/Distribution/Client/ProjectConfig.hs
index 65403a92f01..d26b01888c9 100644
--- a/cabal-install/src/Distribution/Client/ProjectConfig.hs
+++ b/cabal-install/src/Distribution/Client/ProjectConfig.hs
@@ -651,7 +651,17 @@ reportParseResult verbosity filetype filename (OldParser.ParseFailed err) =
 --
 data ProjectPackageLocation =
      ProjectPackageLocalCabalFile FilePath
-   | ProjectPackageLocalDirectory FilePath FilePath -- dir and .cabal file
+   | ProjectPackageLocalDirectory FilePath FilePath
+     -- ^ In @'ProjectPackageLocalDirectory' directory cabalFile@, @directory@
+     -- is expected to be a filepath relative to the root of the
+     -- project. Similarly, @cabalFile@ is also relative to the root of
+     -- of the project.
+     --
+     -- Consequentially, the following should hold:
+     --
+     -- > takeDirectory cabalFile == directory
+     -- > directory </> takeFileName cabalFile == cabalFile
+     --
    | ProjectPackageLocalTarball   FilePath
    | ProjectPackageRemoteTarball  URI
    | ProjectPackageRemoteRepo     SourceRepoList
@@ -1041,7 +1051,10 @@ readSourcePackageLocalDirectory
 readSourcePackageLocalDirectory verbosity dir cabalFile = do
     monitorFiles [monitorFileHashed cabalFile]
     root <- askRoot
-    let location = LocalUnpackedPackage (root </> dir) (Just cabalFile)
+    -- cabalFile is not required to be just the filename, but might be
+    -- relative to the project root.
+    let cabalFileName = takeFileName cabalFile
+    let location = LocalUnpackedPackage (root </> dir) (Just cabalFileName)
     liftIO $ fmap (mkSpecificSourcePackage location)
            . readSourcePackageCabalFile verbosity cabalFile
          =<< BS.readFile (root </> cabalFile)
diff --git a/cabal-install/src/Distribution/Client/Types/PackageLocation.hs b/cabal-install/src/Distribution/Client/Types/PackageLocation.hs
index eb83a931ce2..ba4f105c647 100644
--- a/cabal-install/src/Distribution/Client/Types/PackageLocation.hs
+++ b/cabal-install/src/Distribution/Client/Types/PackageLocation.hs
@@ -24,9 +24,14 @@ type ResolvedPkgLoc = PackageLocation FilePath
 
 data PackageLocation local =
 
-    -- | An unpacked package in the given dir, or current dir,
-    -- with the given .cabal file name within the given dir.
-    -- If Nothing, this will default to @'PackageId' <.> "cabal"@.
+    -- | An unpacked package in the given directory.
+    -- @'LocalUnpackedPackage' directory mCabalFile@, where @directory@ is an
+    -- absolute filepath which points to the root of the *package*.
+    -- I.e., the filepath points to the directory where the '.cabal' file of
+    -- this package can be found.
+    -- If @mCabalFile@ is 'Nothing', then the '.cabal' file can be assumed to
+    -- be '<package-name>.cabal'.
+    -- Otherwise, @mCabalFile@ points to the '.cabal' file within @directory@.
     LocalUnpackedPackage FilePath (Maybe FilePath)
 
     -- | A package as a tarball that's available as a local tarball