diff --git a/Distribution/Package.hs b/Distribution/Package.hs
index d6502efd9c6139216763277055fe6bb5aab03682..5aa0a5270ed6949ad2ff12a75d86df6eae809d60 100644
--- a/Distribution/Package.hs
+++ b/Distribution/Package.hs
@@ -113,7 +113,7 @@ instance Text PackageIdentifier where
 -- * Installed Package Ids
 -- ------------------------------------------------------------
 
--- | An InstalledPackageId uniquely identifies a package instance.
+-- | An InstalledPackageId uniquely identifies an instance of an installed package.
 -- There can be at most one package with a given 'InstalledPackageId'
 -- in a package database, or overlay of databases.
 --
@@ -130,7 +130,8 @@ instance Text InstalledPackageId where
 -- * Package source dependencies
 -- ------------------------------------------------------------
 
--- | describes a source (API) dependency
+-- | Describes a dependency on a source package (API)
+--
 data Dependency = Dependency PackageName VersionRange
                   deriving (Read, Show, Eq)
 
diff --git a/Distribution/Simple/Build/Macros.hs b/Distribution/Simple/Build/Macros.hs
index 250a430df8db68d694ae9722f52581cec962633d..dc25c71612b4ed6b6b2527d7971010a18d8e7ab1 100644
--- a/Distribution/Simple/Build/Macros.hs
+++ b/Distribution/Simple/Build/Macros.hs
@@ -47,6 +47,7 @@ generate _pkg_descr lbi = concat $
     ,"\n\n"
     ]
   | pkgid@(PackageIdentifier name version) <-
+      --TODO: too many conversions from InstalledPackageId to source PackageId
       map (packageId . getLocalPackageInfo lbi) $ externalPackageDeps lbi
   , let (major1:major2:minor:_) = map show (versionBranch version ++ repeat 0)
         pkgname = map fixchar (display name)
diff --git a/Distribution/Simple/Configure.hs b/Distribution/Simple/Configure.hs
index 1f80def0c04d2b720c9fe6323fd323eed4d4d8bb..172d28b0dcd638c2417f9cc8037c4194ada3ec93 100644
--- a/Distribution/Simple/Configure.hs
+++ b/Distribution/Simple/Configure.hs
@@ -306,6 +306,10 @@ configure (pkg_descr0, pbi) cfg
         -- libraries that could possibly be defined by the .cabal file.
         let pid = packageId pkg_descr0
             internalPackageSet = PackageIndex.fromList [ emptyInstalledPackageInfo {
+                  --TODO: should use a per-compiler method to map the source
+                  --      package ID into an installed package id we can use
+                  --      for the internal package set. The open-codes use of
+                  --      InstalledPackageId . display here is a hack.
                   Installed.installedPackageId = InstalledPackageId $ display $ pid,
                   Installed.sourcePackageId = pid
               } ]
@@ -381,6 +385,7 @@ configure (pkg_descr0, pbi) cfg
                ++ "package. To use this feature the package must specify at "
                ++ "least 'cabal-version: >= 1.8'."
 
+        --TODO: sort out this need to keep converting package id types.
         let installedPackageIndex =
                PackageIndex.listToInstalledPackageIndex $
                PackageIndex.allPackages packageSet
diff --git a/Distribution/Simple/LocalBuildInfo.hs b/Distribution/Simple/LocalBuildInfo.hs
index 8228e63ffa148da7b4ee34d6dc47278d7bb8389e..67a795612ec906af623f05e9d7eb8e2fc1150f9b 100644
--- a/Distribution/Simple/LocalBuildInfo.hs
+++ b/Distribution/Simple/LocalBuildInfo.hs
@@ -125,6 +125,12 @@ data ComponentLocalBuildInfo = ComponentLocalBuildInfo {
   }
   deriving (Read, Show)
 
+--TODO: check how these are used. In particular check how we handle
+--      intra-package deps, are they really InstalledPackageId?
+
+--TODO: having to do (packageId . getLocalPackageInfo lbi) to convert
+--      an InstalledPackageId to a PackageId is not really ideal.
+
 componentPackageDeps :: LocalBuildInfo -> ComponentLocalBuildInfo -> [PackageId]
 componentPackageDeps lbi =
   map (packageId.getLocalPackageInfo lbi) . componentInstalledPackageDeps
diff --git a/Distribution/Simple/Register.hs b/Distribution/Simple/Register.hs
index c94076d5002eb6a7c9210eaf19deb4197d411f64..f0cc0986060721fcce58191ccea7db8861f67ebd 100644
--- a/Distribution/Simple/Register.hs
+++ b/Distribution/Simple/Register.hs
@@ -173,6 +173,8 @@ generateRegistrationInfo verbosity pkg lib lbi clbi inplace distPref = do
   --TODO: eliminate pwd!
   pwd <- getCurrentDirectory
 
+  --TODO: the method of setting the InstalledPackageId is compiler specific
+  --      this aspect should be delegated to a per-compiler helper.
   let comp = compiler lbi
   ipid_suffix <-
      if inplace
@@ -192,8 +194,6 @@ generateRegistrationInfo verbosity pkg lib lbi clbi inplace distPref = do
   return installedPkgInfo{ IPI.installedPackageId = ipid }
 
 
-
-
 registerPackage :: Verbosity
                 -> PackageDescription
                 -> Library
@@ -292,6 +292,7 @@ generalInstalledPackageInfo
   -> InstalledPackageInfo
 generalInstalledPackageInfo adjustRelIncDirs pkg lib clbi installDirs =
   InstalledPackageInfo {
+    --TODO: do not open-code this conversion from PackageId to InstalledPackageId
     IPI.installedPackageId = InstalledPackageId (display (packageId pkg)),
     IPI.sourcePackageId    = packageId   pkg,
     IPI.license            = license     pkg,