From: Max Bolingbroke <batterseapower@hotmail.com>
Date: Thu, 31 Jul 2008 01:23:45 +0000 (+0000)
Subject: Document PackageConfig
X-Git-Url: http://git.megacz.com/?p=ghc-hetmet.git;a=commitdiff_plain;h=5b1fbf18b16c504bcd998d1cb7bfa015a79b50df

Document PackageConfig
---

diff --git a/compiler/main/PackageConfig.hs b/compiler/main/PackageConfig.hs
index a93a7e5..9cd6e23 100644
--- a/compiler/main/PackageConfig.hs
+++ b/compiler/main/PackageConfig.hs
@@ -2,7 +2,10 @@
 -- (c) The University of Glasgow, 2004
 --
 
+-- | Package configuration information: essentially the interface to Cabal, with some utilities
 module PackageConfig (
+    -- $package_naming
+    
 	-- * PackageId
 	mkPackageId, packageConfigId, unpackPackageId,
 	
@@ -38,23 +41,29 @@ defaultPackageConfig = emptyInstalledPackageInfo
 -- -----------------------------------------------------------------------------
 -- PackageId (package names with versions)
 
--- Mostly the compiler deals in terms of PackageNames, which don't
+-- $package_naming
+-- #package_naming#
+-- Mostly the compiler deals in terms of 'PackageName's, which don't
 -- have the version suffix.  This is so that we don't need to know the
--- version for the -package-name flag, or know the versions of
--- wired-in packages like base & rts.  Versions are confined to the
+-- version for the @-package-name@ flag, or know the versions of
+-- wired-in packages like @base@ & @rts@.  Versions are confined to the
 -- package sub-system.
 --
 -- This means that in theory you could have multiple base packages installed
--- (for example), and switch between them using -package/-hide-package.
+-- (for example), and switch between them using @-package@/@-hide-package@.
 --
--- A PackageId is a string of the form <pkg>-<version>.
+-- A 'PackageId' is a string of the form @<pkg>-<version>@.
 
+-- | Turn a Cabal 'PackageIdentifier' into a GHC 'PackageId'
 mkPackageId :: PackageIdentifier -> PackageId
 mkPackageId = stringToPackageId . display
 
+-- | Get the GHC 'PackageId' right out of a Cabalish 'PackageConfig'
 packageConfigId :: PackageConfig -> PackageId
 packageConfigId = mkPackageId . package
 
+-- | Try and interpret a GHC 'PackageId' as a cabal 'PackageIdentifer'. Returns @Nothing@ if
+-- we could not parse it as such an object.
 unpackPackageId :: PackageId -> Maybe PackageIdentifier
 unpackPackageId p
   = case [ pid | (pid,"") <- readP_to_S parse str ] of
@@ -62,6 +71,8 @@ unpackPackageId p
         (pid:_) -> Just pid
   where str = packageIdString p
 
+-- | Turn a 'PackageConfig', which contains GHC 'ModuleName's into a Cabal specific
+-- 'InstalledPackageInfo' which contains Cabal 'Distribution.ModuleName.ModuleName's
 packageConfigToInstalledPackageInfo :: PackageConfig -> InstalledPackageInfo
 packageConfigToInstalledPackageInfo
     (pkgconf@(InstalledPackageInfo { exposedModules = e,
@@ -71,6 +82,8 @@ packageConfigToInstalledPackageInfo
     where convert :: Module.ModuleName -> Distribution.ModuleName.ModuleName
           convert = fromJust . simpleParse . moduleNameString
 
+-- | Turn an 'InstalledPackageInfo', which contains Cabal 'Distribution.ModuleName.ModuleName's
+-- into a GHC specific 'PackageConfig' which contains GHC 'ModuleName's
 installedPackageInfoToPackageConfig :: InstalledPackageInfo -> PackageConfig
 installedPackageInfoToPackageConfig
     (pkgconf@(InstalledPackageInfo { exposedModules = e,