Document assumptions LocalUnpackedPackage fields

cabal-install/src/Distribution/Client/ProjectConfig.hs

@@ -667,7 +667,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
@@ -1057,7 +1067,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)

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