diff --git a/Distribution/Compat/ReadP.hs b/Distribution/Compat/ReadP.hs
index 582f4bc40d1762b7891d01f273982efc2a2f9999..e6450af0633aede30d9c52e05603df058050ae7e 100644
--- a/Distribution/Compat/ReadP.hs
+++ b/Distribution/Compat/ReadP.hs
@@ -5,7 +5,6 @@
-- License : BSD-style (see the file libraries/base/LICENSE)
--
-- Maintainer : libraries@haskell.org
--- Stability : provisional
-- Portability : portable
--
-- This is a library of parser combinators, originally written by Koen Claessen.
diff --git a/Distribution/Compiler.hs b/Distribution/Compiler.hs
index 97af9a096dbd38b69e8c2c16b10f3d94a1d66bd6..58381e389dcd06e6ac340793abfc558215320c85 100644
--- a/Distribution/Compiler.hs
+++ b/Distribution/Compiler.hs
@@ -3,11 +3,23 @@
-- Module : Distribution.Compiler
-- Copyright : Isaac Jones 2003-2004
--
--- Maintainer : Isaac Jones <ijones@syntaxpolice.org>
--- Stability : alpha
+-- Maintainer : cabal-devel@haskell.org
-- Portability : portable
--
--- Haskell compiler flavors
+-- This has an enumeration of the various compilers that Cabal knows about. It
+-- also specifies the default compiler. Sadly you'll often see code that does
+-- case analysis on this compiler flavour enumeration like:
+--
+-- > case compilerFlavor comp of
+-- > GHC -> GHC.getInstalledPackages verbosity packageDb progconf
+-- > JHC -> JHC.getInstalledPackages verbosity packageDb progconf
+--
+-- Obviously it would be better to use the proper 'Compiler' abstraction
+-- because that would keep all the compiler-specific code together.
+-- Unfortunately we cannot make this change yet without breaking the
+-- 'UserHooks' api, which would break all custom @Setup.hs@ files, so for the
+-- moment we just have to live with this deficiency. If you're interested, see
+-- ticket #50.
{- All rights reserved.
diff --git a/Distribution/GetOpt.hs b/Distribution/GetOpt.hs
index cb41692d2296f3c35ef1cfbd53bd9a620c0310d9..b35d64fab426762147739f95d3e103ee7be63ca7 100644
--- a/Distribution/GetOpt.hs
+++ b/Distribution/GetOpt.hs
@@ -5,7 +5,6 @@
-- License : BSD-style (see the file libraries/base/LICENSE)
--
-- Maintainer : libraries@haskell.org
--- Stability : experimental
-- Portability : portable
--
-- This library provides facilities for parsing the command-line options
diff --git a/Distribution/InstalledPackageInfo.hs b/Distribution/InstalledPackageInfo.hs
index d6c784036ba4dab3049ba6638cf083edb310c752..8fd9d9ad3e97f6727fc36d692ef0cf433779e287 100644
--- a/Distribution/InstalledPackageInfo.hs
+++ b/Distribution/InstalledPackageInfo.hs
@@ -4,14 +4,23 @@
-- Copyright : (c) The University of Glasgow 2004
--
-- Maintainer : libraries@haskell.org
--- Stability : alpha
-- Portability : portable
--
-- This is the information about an /installed/ package that
-- is communicated to the @hc-pkg@ program in order to register
-- a package. @ghc-pkg@ now consumes this package format (as of verison
-- 6.4). This is specific to GHC at the moment.
-
+--
+-- The @.cabal@ file format is for describing a package that is not yet
+-- installed. It has a lot of flexibility like conditionals and dependency
+-- ranges. As such that format is not at all suitable for describing a package
+-- that has already been built and installed. By the time we get to that stage
+-- we have resolved all conditionals and resolved dependency version
+-- constraints to exact versions of dependent packages. So this module defines
+-- the 'InstalledPackageInfo' data structure that contains all the info we keep
+-- about an installed package. There is a parser and pretty printer. The
+-- textual format is rather simpler than the @.cabal@ format, there are no
+-- sections for example.
{- All rights reserved.
diff --git a/Distribution/License.hs b/Distribution/License.hs
index 9d0349f63d38cf0d8a70d1b24dbdceb5e02b104f..dc21907e5e5a2151aafa24bcb275604b8381b7d0 100644
--- a/Distribution/License.hs
+++ b/Distribution/License.hs
@@ -3,17 +3,18 @@
-- Module : Distribution.License
-- Copyright : Isaac Jones 2003-2005
--
--- Maintainer : Isaac Jones <ijones@syntaxpolice.org>
--- Stability : alpha
+-- Maintainer : cabal-devel@haskell.org
-- Portability : portable
--
-- The License datatype. For more information about these and other
-- open-source licenses, you may visit <http://www.opensource.org/>.
--
--- I am not a lawyer, but as a general guideline, most Haskell
--- software seems to be released under a BSD3 license, which is very
--- open and free. If you don't want to restrict the use of your
--- software or its source code, use BSD3 or PublicDomain.
+-- The @.cabal@ file allows you to specify a license file. Of course you can
+-- use any license you like but people often pick common open source licenses
+-- and it's useful if we can automatically recognise that (eg so we can display
+-- it on the hackage web pages). So you can also specify the license itself in
+-- the @.cabal@ file from a short enumeration defined in this module. It
+-- includes 'GPL', 'LGPL' and 'BSD3' licenses.
{- All rights reserved.
diff --git a/Distribution/Make.hs b/Distribution/Make.hs
index 931fac7bee2ffec08b15042cbcbdf2c75e804896..b103e91a82e7be60b9e014ad603ae48c5fd19d4f 100644
--- a/Distribution/Make.hs
+++ b/Distribution/Make.hs
@@ -3,10 +3,18 @@
-- Module : Distribution.Make
-- Copyright : Martin Sjögren 2004
--
--- Maintainer : Isaac Jones <ijones@syntaxpolice.org>
--- Stability : alpha
+-- Maintainer : cabal-devel@haskell.org
-- Portability : portable
--
+-- This is an alternative build system that delegates everything to the @make@
+-- program. All the commands just end up calling @make@ with appropriate
+-- arguments. The intention was to allow preexisting packages that used
+-- makefiles to be wrapped into Cabal packages. In practice essentially all
+-- such packages were converted over to the \"Simple\" build system instead.
+-- Consequently this module is not used much and it certainly only sees cursory
+-- maintenance and no testing. Perhaps at some point we should stop pretending
+-- that it works.
+--
-- Uses the parsed command-line from Distribution.Setup in order to build
-- Haskell tools using a backend build system based on make. Obviously we
-- assume that there is a configure script, and that after the ConfigCmd has
diff --git a/Distribution/ModuleName.hs b/Distribution/ModuleName.hs
index 9967d75f6b6b4204868c8d2ac183dd33c25d07d9..3adc0c478dbef443df0ee5b27e7989f824a81005 100644
--- a/Distribution/ModuleName.hs
+++ b/Distribution/ModuleName.hs
@@ -3,11 +3,10 @@
-- Module : Distribution.ModuleName
-- Copyright : Duncan Coutts 2008
--
--- Maintainer : Duncan Coutts <duncan@haskell.org>
--- Stability : alpha
+-- Maintainer : cabal-devel@haskell.org
-- Portability : portable
--
--- Haskell module names
+-- Data type for Haskell module names.
{- All rights reserved.
diff --git a/Distribution/Package.hs b/Distribution/Package.hs
index 9674f1ff698a6f5b436c9475fcfc48d6832c8283..f303eada952d13dbe78cfd564ac54111821de524 100644
--- a/Distribution/Package.hs
+++ b/Distribution/Package.hs
@@ -3,11 +3,13 @@
-- Module : Distribution.Package
-- Copyright : Isaac Jones 2003-2004
--
--- Maintainer : Isaac Jones <ijones@syntaxpolice.org>
--- Stability : alpha
+-- Maintainer : cabal-devel@haskell.org
-- Portability : portable
--
--- Packages are fundamentally just a name and a version.
+-- Defines a package identifier along with a parser and pretty printer for it.
+-- 'PackageIdentifier's consist of a name and an exact version. It also defines
+-- a 'Dependency' data type. A dependency is a package name and a version
+-- range, like @\"foo >= 1.2 && < 2\"@.
{- All rights reserved.
diff --git a/Distribution/PackageDescription.hs b/Distribution/PackageDescription.hs
index c161ebc6d741f86c8c0959cd0e7e5580109102c7..48f79e0f93db1089b71be9aa81dd9ed6cb5ec2da 100644
--- a/Distribution/PackageDescription.hs
+++ b/Distribution/PackageDescription.hs
@@ -3,11 +3,21 @@
-- Module : Distribution.PackageDescription
-- Copyright : Isaac Jones 2003-2005
--
--- Maintainer : Isaac Jones <ijones@syntaxpolice.org>
--- Stability : alpha
+-- Maintainer : cabal-devel@haskell.org
-- Portability : portable
--
--- Package description and parsing.
+-- This defines the data structure for the @.cabal@ file format. There are
+-- several parts to this structure. It has top level info and then 'Library'
+-- and 'Executable' sections each of which have associated 'BuildInfo' data
+-- that's used to build the library or exe. To further complicate things there
+-- is both a 'PackageDescription' and a 'GenericPackageDescription'. This
+-- distinction relates to cabal configurations. When we initially read a
+-- @.cabal@ file we get a 'GenericPackageDescription' which has all the
+-- conditional sections. Before actually building a package we have to decide
+-- on each conditional. Once we've done that we get a 'PackageDescription'.
+-- It was done this way initially to avoid breaking too much stuff when the
+-- feature was introduced. It could probably do with being rationalised at some
+-- point to make it simpler.
{- All rights reserved.
diff --git a/Distribution/PackageDescription/Check.hs b/Distribution/PackageDescription/Check.hs
index 5231c7c9feb59cb5a7534502b30e0a11416e5e99..e0c965b1542085db0546b12d164b736f7d94fb2e 100644
--- a/Distribution/PackageDescription/Check.hs
+++ b/Distribution/PackageDescription/Check.hs
@@ -3,11 +3,21 @@
-- Module : Distribution.PackageDescription.Check
-- Copyright : Lennart Kolmodin 2008
--
--- Maintainer : Lennart Kolmodin <kolmodin@gentoo.org>
--- Stability : alpha
+-- Maintainer : cabal-devel@haskell.org
-- Portability : portable
--
--- This module provides functionality to check for common mistakes.
+-- This has code for checking for various problems in packages. There is one
+-- set of checks that just looks at a 'PackageDescription' in isolation and
+-- another set of checks that also looks at files in the package. Some of the
+-- checks are basic sanity checks, others are portability standards that we'd
+-- like to encourage. There is a 'PackageCheck' type that distinguishes the
+-- different kinds of check so we can see which ones are appropriate to report
+-- in different situations. This code gets uses when configuring a package when
+-- we consider only basic problems. The higher standard is uses when when
+-- preparing a source tarball and by hackage when uploading new packages. The
+-- reason for this is that we want to hold packages that are expected to be
+-- distributed to a higher standard than packages that are only ever expected
+-- to be used on the author's own environment.
{- All rights reserved.
diff --git a/Distribution/PackageDescription/Configuration.hs b/Distribution/PackageDescription/Configuration.hs
index d8c39653e3547931cbe453e44d44321447541254..4ab93a17f0b1212f73f5ae48b7a42404f36000d6 100644
--- a/Distribution/PackageDescription/Configuration.hs
+++ b/Distribution/PackageDescription/Configuration.hs
@@ -9,11 +9,14 @@
-- Module : Distribution.Configuration
-- Copyright : Thomas Schilling, 2007
--
--- Maintainer : Isaac Jones <ijones@syntaxpolice.org>
--- Stability : alpha
+-- Maintainer : cabal-devel@haskell.org
-- Portability : portable
--
--- Configurations
+-- This is about the cabal configurations feature. It exports
+-- 'finalizePackageDescription' and 'flattenPackageDescription' which are
+-- functions for converting 'GenericPackageDescription's down to
+-- 'PackageDescription's. It has code for working with the tree of conditions
+-- and resolving or flattening conditions.
{- All rights reserved.
diff --git a/Distribution/PackageDescription/Parse.hs b/Distribution/PackageDescription/Parse.hs
index 7340fd3db79d5e8dd0f3506668fa7a9336392993..21f9cd222b4b8f18ec9192a403234bd8a7fb540b 100644
--- a/Distribution/PackageDescription/Parse.hs
+++ b/Distribution/PackageDescription/Parse.hs
@@ -3,11 +3,13 @@
-- Module : Distribution.PackageDescription.Parse
-- Copyright : Isaac Jones 2003-2005
--
--- Maintainer : Isaac Jones <ijones@syntaxpolice.org>
--- Stability : alpha
+-- Maintainer : cabal-devel@haskell.org
-- Portability : portable
--
--- Package description and parsing.
+-- This defined parsers and partial pretty printers for the @.cabal@ format.
+-- Some of the complexity in this module is due to the fact that we have to be
+-- backwards compatible with old @.cabal@ files, so there's code to translate
+-- into the newer structure.
{- All rights reserved.
diff --git a/Distribution/ParseUtils.hs b/Distribution/ParseUtils.hs
index f3b3ada846b13f8c27151e9b9f3c1b4433ae2ec3..3f7f04a55d8c993a346418fcca0831eea1007461 100644
--- a/Distribution/ParseUtils.hs
+++ b/Distribution/ParseUtils.hs
@@ -3,12 +3,17 @@
-- Module : Distribution.ParseUtils
-- Copyright : (c) The University of Glasgow 2004
--
--- Maintainer : libraries@haskell.org
--- Stability : alpha
+-- Maintainer : cabal-devel@haskell.org
-- Portability : portable
--
--- Utilities for parsing PackageDescription and InstalledPackageInfo.
-
+-- Utilities for parsing 'PackageDescription' and 'InstalledPackageInfo'.
+--
+-- The @.cabal@ file format is not trivial, especially with the introduction
+-- of configurations and the section syntax that goes with that. This module
+-- has a bunch of parsing functions that is used by the @.cabal@ parser and a
+-- couple others. It has the parsing framework code and also little parsers for
+-- many of the formats we get in various @.cabal@ file fields, like module
+-- names, comma separated lists etc.
{- All rights reserved.
diff --git a/Distribution/ReadE.hs b/Distribution/ReadE.hs
index d0bcf13cb359a948e8528c4bc72178f2e3332dd3..01069f673aa4ddb32fb7089ed822061f846348eb 100644
--- a/Distribution/ReadE.hs
+++ b/Distribution/ReadE.hs
@@ -3,8 +3,7 @@
-- Module : Distribution.ReadE
-- Copyright : Jose Iborra 2008
--
--- Maintainer : Isaac Jones <ijones@syntaxpolice.org>
--- Stability : alpha
+-- Maintainer : cabal-devel@haskell.org
-- Portability : portable
--
-- Simple parsing with failure
diff --git a/Distribution/Simple.hs b/Distribution/Simple.hs
index 48f281a2b3203102f81dcb21e3bb2ab48228b9cc..68ee47790938d47211147e413ee3e6f7e49129ea 100644
--- a/Distribution/Simple.hs
+++ b/Distribution/Simple.hs
@@ -3,18 +3,26 @@
-- Module : Distribution.Simple
-- Copyright : Isaac Jones 2003-2005
--
--- Maintainer : Isaac Jones <ijones@syntaxpolice.org>
--- Stability : alpha
+-- Maintainer : cabal-devel@haskell.org
-- Portability : portable
--
--- Explanation: Simple build system; basically the interface for
--- Distribution.Simple.\* modules. When given the parsed command-line
--- args and package information, is able to perform basic commands
--- like configure, build, install, register, etc.
+-- This is the command line front end to the Simple build system. When given
+-- the parsed command-line args and package information, is able to perform
+-- basic commands like configure, build, install, register, etc.
+--
+-- This module exports the main functions that Setup.hs scripts use. It
+-- re-exports the 'UserHooks' type, the standard entry points like
+-- 'defaultMain' and 'defaultMainWithHooks' and the predefined sets of
+-- 'UserHooks' that custom @Setup.hs@ scripts can extend to add their own
+-- behaviour.
--
-- This module isn't called \"Simple\" because it's simple. Far from
-- it. It's called \"Simple\" because it does complicated things to
-- simple software.
+--
+-- The original idea was that there could be different build systems that all
+-- presented the same compatible command line interfaces. There is still a
+-- "Distribution.Make" system but in practice no packages use it.
{- All rights reserved.
diff --git a/Distribution/Simple/Build.hs b/Distribution/Simple/Build.hs
index 5396f68f6bc5e9ed76c20c1f2c64edfcb6525e7d..14a0e964ba2dce867f75f1a50fd042c812682878 100644
--- a/Distribution/Simple/Build.hs
+++ b/Distribution/Simple/Build.hs
@@ -3,12 +3,23 @@
-- Module : Distribution.Simple.Build
-- Copyright : Isaac Jones 2003-2005
--
--- Maintainer : Isaac Jones <ijones@syntaxpolice.org>
--- Stability : alpha
+-- Maintainer : cabal-devel@haskell.org
-- Portability : portable
--
--- Invokes the "Distribution.Compiler"s to build the library and
--- executables in this package.
+-- This is the entry point to actually building the modules in a package. It
+-- doesn't actually do much itself, most of the work is delegated to
+-- compiler-specific actions. It does do some non-compiler specific bits like
+-- running pre-processors.
+--
+-- There's some stuff to do with generating @makefiles@ which is a well hidden
+-- feature that's used to build libraries inside the GHC build system but which
+-- we'd like to kill off and replace with something better (doing our own
+-- dependency analysis properly).
+--
+-- Half the module is dedicated to generating the @Paths_@/pkgname/ module.
+-- This is a module that Cabal generates for the benefit of packages. It
+-- enables them to find their version number and find any installed data files
+-- at runtime. This code should probably be split off into another module.
{- Copyright (c) 2003-2005, Isaac Jones
All rights reserved.
diff --git a/Distribution/Simple/BuildPaths.hs b/Distribution/Simple/BuildPaths.hs
index eb618646b6af0e46caa0ddf5f8c7520421dfc6c7..8fd09d46408d873b4129c484f63042cbf129e249 100644
--- a/Distribution/Simple/BuildPaths.hs
+++ b/Distribution/Simple/BuildPaths.hs
@@ -4,8 +4,7 @@
-- Copyright : Isaac Jones 2003-2004,
-- Duncan Coutts 2008
--
--- Maintainer : Isaac Jones <ijones@syntaxpolice.org>
--- Stability : alpha
+-- Maintainer : cabal-devel@haskell.org
-- Portability : portable
--
-- A bunch of dirs, paths and file names used for intermediate build steps.
diff --git a/Distribution/Simple/Command.hs b/Distribution/Simple/Command.hs
index 66b21867ba34b8b3685d3c85f559757a65d6dc47..62cda027f57aee545f0533cac6fe3209c0447414 100644
--- a/Distribution/Simple/Command.hs
+++ b/Distribution/Simple/Command.hs
@@ -3,12 +3,16 @@
-- Module : Distribution.Simple.Command
-- Copyright : Duncan Coutts 2007
--
--- Maintainer : Duncan Coutts <duncan@haskell.org>
--- Stability : alpha
+-- Maintainer : cabal-devel@haskell.org
-- Portability : portable
--
--- Explanation: Data types and parser for the standard command-line
--- setup.
+-- This is to do with command line handling. The Cabal command line is
+-- organised into a number of named sub-commands (much like darcs). The
+-- 'CommandUI' abstraction represents one of these sub-commands, with a name,
+-- description, a set of flags. Commands can be associated with actions and
+-- run. It handles some common stuff automatically, like the @--help@ and
+-- command line completion flags. It is designed to allow other tools make
+-- derived commands. This feature is used heavily in @cabal-install@.
{- All rights reserved.
diff --git a/Distribution/Simple/Compiler.hs b/Distribution/Simple/Compiler.hs
index 5657f070b2b9219dfac6bb25abddbec852738747..75cad0537849734f02f1119b555eb322bbf7b5c8 100644
--- a/Distribution/Simple/Compiler.hs
+++ b/Distribution/Simple/Compiler.hs
@@ -3,11 +3,19 @@
-- Module : Distribution.Simple.Compiler
-- Copyright : Isaac Jones 2003-2004
--
--- Maintainer : Isaac Jones <ijones@syntaxpolice.org>
--- Stability : alpha
+-- Maintainer : cabal-devel@haskell.org
-- Portability : portable
--
--- Haskell implementations.
+-- This should be a much more sophisticated abstraction than it is. Currently
+-- it's just a bit of data about the compiler, like it's flavour and name and
+-- version. The reason it's just data is because currently it has to be in
+-- 'Read' and 'Show' so it can be saved along with the 'LocalBuildInfo'. The
+-- only interesting bit of info it contains is a mapping between language
+-- extensions and compiler command line flags. This module also defines a
+-- 'PackageDB' type which is used to refer to package databases. Most compilers
+-- only know about a single global package collection but GHC has a global and
+-- per-user one and it lets you create arbitrary other package databases. We do
+-- not yet fully support this latter feature.
{- All rights reserved.
diff --git a/Distribution/Simple/Configure.hs b/Distribution/Simple/Configure.hs
index a0c9833847997b489c902343995d5c60b11c65b6..6de712f7202288e6f08cd4e45fa1f740b42d0f74 100644
--- a/Distribution/Simple/Configure.hs
+++ b/Distribution/Simple/Configure.hs
@@ -3,12 +3,22 @@
-- Module : Distribution.Simple.Configure
-- Copyright : Isaac Jones 2003-2005
--
--- Maintainer : Isaac Jones <ijones@syntaxpolice.org>
--- Stability : alpha
+-- Maintainer : cabal-devel@haskell.org
-- Portability : portable
--
--- Explanation: Perform the \"@.\/setup configure@\" action.
--- Outputs the @dist\/setup-config@ file.
+-- This deals with the /configure/ phase. It provides the 'configure' action
+-- which is given the package description and configure flags. It then tries
+-- to: configure the compiler; resolves any conditionals in the package
+-- description; resolve the package dependencies; check if all the extensions
+-- used by this package are supported by the compiler; check that all the build
+-- tools are available (including version checks if appropriate); checks for
+-- any required @pkg-config@ packages (updating the 'BuildInfo' with the
+-- results)
+--
+-- Then based on all this it saves the info in the 'LocalBuildInfo' and writes
+-- it out to the @dist\/setup-config@ file. It also displays various details to
+-- the user, the amount of information displayed depending on the verbosity
+-- level.
{- All rights reserved.
diff --git a/Distribution/Simple/GHC.hs b/Distribution/Simple/GHC.hs
index 538067708bb8ca16a3a98b1f836c88f34bdeb669..10e3f399b9cd385491bcf5dafab28638618d89fc 100644
--- a/Distribution/Simple/GHC.hs
+++ b/Distribution/Simple/GHC.hs
@@ -3,13 +3,34 @@
-- Module : Distribution.Simple.GHC
-- Copyright : Isaac Jones 2003-2007
--
--- Maintainer : Isaac Jones <ijones@syntaxpolice.org>
--- Stability : alpha
+-- Maintainer : cabal-devel@haskell.org
-- Portability : portable
--
--- Build and Install implementations for GHC. See
--- 'Distribution.Simple.GHC.PackageConfig.GHCPackageConfig' for
--- registration-related stuff.
+-- This is a fairly large module. It contains most of the GHC-specific code for
+-- configuring, building and installing packages. It also exports a function
+-- for finding out what packages are already installed. Configuring involves
+-- finding the @ghc@ and @ghc-pkg@ programs, finding what language extensions
+-- this version of ghc supports and returning a 'Compiler' value.
+--
+-- 'getInstalledPackages' involves calling the @ghc-pkg@ program to find out
+-- what packages are installed.
+--
+-- Building is somewhat complex as there is quite a bit of information to take
+-- into account. We have to build libs and programs, possibly for profiling and
+-- shared libs. We have to support building libraries that will be usable by
+-- GHCi and also ghc's @-split-objs@ feature. We have to compile any C files
+-- using ghc. Linking, especially for @split-objs@ is remarkably complex,
+-- partly because there tend to be 1,000's of @.o@ files and this can often be
+-- more than we can pass to the @ld@ or @ar@ programs in one go.
+--
+-- There is also some code for generating @Makefiles@ but the less said about
+-- that the better.
+--
+-- Installing for libs and exes involves finding the right files and copying
+-- them to the right places. One of the more tricky things about this module is
+-- remembering the layout of files in the build directory (which is not
+-- explicitly documented) and thus what search dirs are used for various kinds
+-- of files.
{- Copyright (c) 2003-2005, Isaac Jones
All rights reserved.
diff --git a/Distribution/Simple/GHC/IPI641.hs b/Distribution/Simple/GHC/IPI641.hs
index 210ca1ac445c9fb588267c7a346f8a1ddf050142..3bbe8cac2d16810222f3a6bacda2ec5d1e6b2eae 100644
--- a/Distribution/Simple/GHC/IPI641.hs
+++ b/Distribution/Simple/GHC/IPI641.hs
@@ -3,8 +3,7 @@
-- Module : Distribution.Simple.GHC.IPI641
-- Copyright : (c) The University of Glasgow 2004
--
--- Maintainer : libraries@haskell.org
--- Stability : alpha
+-- Maintainer : cabal-devel@haskell.org
-- Portability : portable
--
diff --git a/Distribution/Simple/GHC/IPI642.hs b/Distribution/Simple/GHC/IPI642.hs
index 30e5a51a6b30c6ca9ef11357488e1c6637717a0b..01200591e237b79f4724597de41f5a4e388532be 100644
--- a/Distribution/Simple/GHC/IPI642.hs
+++ b/Distribution/Simple/GHC/IPI642.hs
@@ -3,8 +3,7 @@
-- Module : Distribution.Simple.GHC.IPI642
-- Copyright : (c) The University of Glasgow 2004
--
--- Maintainer : libraries@haskell.org
--- Stability : alpha
+-- Maintainer : cabal-devel@haskell.org
-- Portability : portable
--
diff --git a/Distribution/Simple/Haddock.hs b/Distribution/Simple/Haddock.hs
index 33ee772391d09e24d24c1ffa02d024412fe44b06..2fa8922a8a528314cb408ac8c19d1c42e5afdab8 100644
--- a/Distribution/Simple/Haddock.hs
+++ b/Distribution/Simple/Haddock.hs
@@ -3,13 +3,18 @@
-- Module : Distribution.Simple.Haddock
-- Copyright : Isaac Jones 2003-2005
--
--- Maintainer : Isaac Jones <ijones@syntaxpolice.org>
--- Stability : alpha
+-- Maintainer : cabal-devel@haskell.org
-- Portability : portable
--
--- Invokes haddock to generate api documentation for libraries and optinally
--- executables in this package. Also has support for generating
--- syntax-highlighted source with HsColour and linking the haddock docs to it.
+-- This module deals with the @haddock@ and @hscolour@ commands. Sadly this is
+-- a rather complicated module. It deals with two versions of haddock (0.x and
+-- 2.x). It has to do pre-processing for haddock 0.x which involves
+-- \'unlit\'ing and using @-DHADDOCK@ for any source code that uses @cpp@. It
+-- uses information about installed packages (from @ghc-pkg@) to find the
+-- locations of documentation for dependent packages, so it can create links.
+--
+-- The @hscolour@ support allows generating html versions of the original
+-- source, with coloured syntax highlighting.
{- All rights reserved.
diff --git a/Distribution/Simple/Hugs.hs b/Distribution/Simple/Hugs.hs
index c9ceb120874533884ad7417eba78b72bcbf1f93b..5130ab7691629cec2ef8f29dfca8c28c492194d7 100644
--- a/Distribution/Simple/Hugs.hs
+++ b/Distribution/Simple/Hugs.hs
@@ -3,11 +3,11 @@
-- Module : Distribution.Simple.Hugs
-- Copyright : Isaac Jones 2003-2006
--
--- Maintainer : Isaac Jones <ijones@syntaxpolice.org>
--- Stability : alpha
+-- Maintainer : cabal-devel@haskell.org
-- Portability : portable
--
--- Build and install functionality for Hugs.
+-- This module contains most of the NHC-specific code for configuring, building
+-- and installing packages.
{- Copyright (c) 2003-2005, Isaac Jones
All rights reserved.
diff --git a/Distribution/Simple/Install.hs b/Distribution/Simple/Install.hs
index 7c1adb2d76e62400b722106418e7b9c23e226425..1a209d47deb78e288d2e098d0dbcae4f94df171b 100644
--- a/Distribution/Simple/Install.hs
+++ b/Distribution/Simple/Install.hs
@@ -3,13 +3,13 @@
-- Module : Distribution.Simple.Install
-- Copyright : Isaac Jones 2003-2004
--
--- Maintainer : Isaac Jones <ijones@syntaxpolice.org>
--- Stability : alpha
+-- Maintainer : cabal-devel@haskell.org
-- Portability : portable
--
--- Explanation: Perform the \"@.\/setup install@\" and \"@.\/setup
--- copy@\" actions. Move files into place based on the prefix
--- argument.
+-- This is the entry point into installing a built package. Performs the
+-- \"@.\/setup install@\" and \"@.\/setup copy@\" actions. It moves files into
+-- place based on the prefix argument. It does the generic bits and then calls
+-- compiler-specific functions to do the rest.
{- All rights reserved.
diff --git a/Distribution/Simple/InstallDirs.hs b/Distribution/Simple/InstallDirs.hs
index 06800aad210f5277a641bb394acedf0c446705a1..11aff595e2d4564924b7839649f158b9f34c2b25 100644
--- a/Distribution/Simple/InstallDirs.hs
+++ b/Distribution/Simple/InstallDirs.hs
@@ -9,15 +9,17 @@
-- Module : Distribution.Simple.InstallDirs
-- Copyright : Isaac Jones 2003-2004
--
--- Maintainer : Isaac Jones <ijones@syntaxpolice.org>
--- Stability : alpha
+-- Maintainer : cabal-devel@haskell.org
-- Portability : portable
--
--- Definition of the 'LocalBuildInfo' data type. This is basically
--- the information that is gathered by the end of the configuration
--- step which could include package information from ghc-pkg, flags
--- the user passed to configure, and the location of tools in the
--- PATH.
+-- This manages everything to do with where files get installed (though does
+-- not get involved with actually doing any installation). It provides an
+-- 'InstallDirs' type which is a set of directories for where to install
+-- things. It also handles the fact that we use templates in these install
+-- dirs. For example most install dirs are relative to some @$prefix@ and by
+-- changing the prefix all other dirs still end up changed appropriately. So it
+-- provides a 'PathTemplate' type and functions for substituting for these
+-- templates.
{- All rights reserved.
diff --git a/Distribution/Simple/JHC.hs b/Distribution/Simple/JHC.hs
index b50e0e6da11266f59585f1ada8428cb3a810efd5..91ac0daa54810d5efbca0db0ed715477a1fef209 100644
--- a/Distribution/Simple/JHC.hs
+++ b/Distribution/Simple/JHC.hs
@@ -3,11 +3,11 @@
-- Module : Distribution.Simple.JHC
-- Copyright : Isaac Jones 2003-2006
--
--- Maintainer : Isaac Jones <ijones@syntaxpolice.org>
--- Stability : alpha
+-- Maintainer : cabal-devel@haskell.org
-- Portability : portable
--
--- Build and install functionality for the JHC compiler.
+-- This module contains most of the JHC-specific code for configuring, building
+-- and installing packages.
{- Copyright (c) 2003-2005, Isaac Jones
All rights reserved.
diff --git a/Distribution/Simple/LocalBuildInfo.hs b/Distribution/Simple/LocalBuildInfo.hs
index 1e4bf21e8dcbed3188dd9fdf30686ca8933100c8..04812ea40b824a59173aa3681549ca98628409a5 100644
--- a/Distribution/Simple/LocalBuildInfo.hs
+++ b/Distribution/Simple/LocalBuildInfo.hs
@@ -3,15 +3,16 @@
-- Module : Distribution.Simple.LocalBuildInfo
-- Copyright : Isaac Jones 2003-2004
--
--- Maintainer : Isaac Jones <ijones@syntaxpolice.org>
--- Stability : alpha
+-- Maintainer : cabal-devel@haskell.org
-- Portability : portable
--
--- Definition of the 'LocalBuildInfo' data type. This is basically
--- the information that is gathered by the end of the configuration
--- step which could include package information from ghc-pkg, flags
--- the user passed to configure, and the location of tools in the
--- PATH.
+-- Once a package has been configured we have resolved conditionals and
+-- dependencies, configured the compiler and other needed external programs.
+-- The 'LocalBuildInfo' is used to hold all this information. It holds the
+-- install dirs, the compiler, the exact package dependencies, the configured
+-- programs, the package database to use and a bunch of miscellaneous configure
+-- flags. It gets saved and reloaded from a file (@dist/setup-config@). It gets
+-- passed in to very many subsequent build actions.
{- All rights reserved.
diff --git a/Distribution/Simple/NHC.hs b/Distribution/Simple/NHC.hs
index b39821c363b0cca3e96527191e35c766be2c43bc..0f1131417c39983acfa42a2830363e7200557899 100644
--- a/Distribution/Simple/NHC.hs
+++ b/Distribution/Simple/NHC.hs
@@ -3,10 +3,11 @@
-- Module : Distribution.Simple.NHC
-- Copyright : Isaac Jones 2003-2006
--
--- Maintainer : Isaac Jones <ijones@syntaxpolice.org>
--- Stability : alpha
+-- Maintainer : cabal-devel@haskell.org
-- Portability : portable
--
+-- This module contains most of the NHC-specific code for configuring, building
+-- and installing packages.
{- Copyright (c) 2003-2005, Isaac Jones
All rights reserved.
diff --git a/Distribution/Simple/PackageIndex.hs b/Distribution/Simple/PackageIndex.hs
index f539b7cf37d1543e58910713d55cec03a890b4ce..bd2aab4b8d69e53d23400dc063b724e5ceeec1d5 100644
--- a/Distribution/Simple/PackageIndex.hs
+++ b/Distribution/Simple/PackageIndex.hs
@@ -10,14 +10,12 @@
-- Copyright : (c) David Himmelstrup 2005,
-- Bjorn Bringert 2007,
-- Duncan Coutts 2008
--- License : BSD-like
--
--- Maintainer : Duncan Coutts <duncan@haskell.org>
--- Stability : provisional
+-- Maintainer : cabal-devel@haskell.org
-- Portability : portable
--
-- An index of packages.
------------------------------------------------------------------------------
+--
module Distribution.Simple.PackageIndex (
-- * Package index data type
PackageIndex,
diff --git a/Distribution/Simple/PackageSet.hs b/Distribution/Simple/PackageSet.hs
index 9a7e43d59e45d57f7c323cb46e5cd732725d60b0..d74e87d49db1e4b763449e18c593f41e759f8f99 100644
--- a/Distribution/Simple/PackageSet.hs
+++ b/Distribution/Simple/PackageSet.hs
@@ -10,14 +10,12 @@
-- Copyright : (c) David Himmelstrup 2005,
-- Bjorn Bringert 2007,
-- Duncan Coutts 2008
--- License : BSD-like
--
--- Maintainer : Duncan Coutts <duncan@haskell.org>
--- Stability : provisional
+-- Maintainer : cabal-devel@haskell.org
-- Portability : portable
--
--- An set of packages.
------------------------------------------------------------------------------
+-- A set of packages.
+--
module Distribution.Simple.PackageSet (
-- * Package set data type
PackageSet,
diff --git a/Distribution/Simple/PreProcess.hs b/Distribution/Simple/PreProcess.hs
index bbefdba07ce6b13b328c14a8adadd98edcc0bf11..3e3e96f099522049e2d4e529148e31fcce88d555 100644
--- a/Distribution/Simple/PreProcess.hs
+++ b/Distribution/Simple/PreProcess.hs
@@ -1,19 +1,20 @@
-----------------------------------------------------------------------------
-- |
-- Module : Distribution.Simple.PreProcess
+-- Copyright : (c) 2003-2005, Isaac Jones, Malcolm Wallace
--
--- Maintainer : Isaac Jones <ijones@syntaxpolice.org>
--- Stability : alpha
+-- Maintainer : cabal-devel@haskell.org
-- Portability : portable
--
---
--- PreProcessors are programs or functions which input a filename and
--- output a Haskell file. The general form of a preprocessor is input
--- Foo.pp and output Foo.hs (where /pp/ is a unique extension that
--- tells us which preprocessor to use eg. gc, ly, cpphs, x, y, etc.).
--- Once a PreProcessor has been added to Cabal, either here or with
--- 'Distribution.Simple.UserHooks', if Cabal finds a Foo.pp, it'll run the given
--- preprocessor which should output a Foo.hs.
+-- This defines a 'PreProcessor' abstraction which represents a pre-processor
+-- that can transform one kind of file into another. There is also a
+-- 'PPSuffixHandler' which is a combination of a file extension and a function
+-- for configuring a 'PreProcessor'. It defines a bunch of known built-in
+-- preprocessors like @cpp@, @cpphs@, @c2hs@, @hsc2hs@, @happy@, @alex@ etc and
+-- lists them in 'knownSuffixHandlers'. On top of this it provides a function
+-- for actually preprocessing some sources given a bunch of known suffix
+-- handlers. This module is not as good as it could be, it could really do with
+-- a rewrite to address some of the problems we have with pre-processors.
{- Copyright (c) 2003-2005, Isaac Jones, Malcolm Wallace
All rights reserved.
diff --git a/Distribution/Simple/PreProcess/Unlit.hs b/Distribution/Simple/PreProcess/Unlit.hs
index b30e2b3c0413c5db8b4a6f1177ea22aa34fe6519..891ac586aa9f739be2e2fbd3663612f1d2a79236 100644
--- a/Distribution/Simple/PreProcess/Unlit.hs
+++ b/Distribution/Simple/PreProcess/Unlit.hs
@@ -3,8 +3,7 @@
-- Module : Distribution.Simple.PreProcess.Unlit
-- Copyright : ...
--
--- Maintainer : Malcolm Wallace <Malcolm.Wallace@cs.york.ac.uk>
--- Stability : Stable
+-- Maintainer : cabal-devel@haskell.org
-- Portability : portable
--
-- Remove the \"literal\" markups from a Haskell source file, including
diff --git a/Distribution/Simple/Program.hs b/Distribution/Simple/Program.hs
index 86c127c72b59fdba9d17c90ca56d22a2067cb326..4467d8befef89004455608a09c42fef555f4902f 100644
--- a/Distribution/Simple/Program.hs
+++ b/Distribution/Simple/Program.hs
@@ -3,12 +3,22 @@
-- Module : Distribution.Simple.Program
-- Copyright : Isaac Jones 2006
--
--- Maintainer : Isaac Jones <ijones@syntaxpolice.org>
--- Stability : alpha
--- Portability : GHC, Hugs
+-- Maintainer : cabal-devel@haskell.org
+-- Portability : portable
--
--- Explanation: A program is basically a name, a location, and some
--- arguments.
+-- This provides an abstraction which deals with configuring and running
+-- programs. A 'Program' is a static notion of a known program. A
+-- 'ConfiguredProgram' is a 'Program' that has been found on the current
+-- machine and is ready to be run (possibly with some user-supplied default
+-- args). Configuring a program involves finding its location and if necessary
+-- finding its version. There is also a 'ProgramConfiguration' type which holds
+-- configured and not-yet configured programs. It is the parameter to lots of
+-- actions elsewhere in Cabal that need to look up and run programs. If we had
+-- a Cabal monad, the 'ProgramConfiguration' would probably be a reader or
+-- state component of it.
+--
+-- The module also defines all the known built-in 'Program's and the
+-- 'defaultProgramConfiguration' which contains them all.
--
-- One nice thing about using it is that any program that is
-- registered with Cabal will get some \"configure\" and \".cabal\"
diff --git a/Distribution/Simple/Register.hs b/Distribution/Simple/Register.hs
index 036c0b3896d2dba30bea6c4a34a76478c3847e2b..8a887d8c2c454e26408fc378274c5e1bee57b513 100644
--- a/Distribution/Simple/Register.hs
+++ b/Distribution/Simple/Register.hs
@@ -3,12 +3,24 @@
-- Module : Distribution.Simple.Register
-- Copyright : Isaac Jones 2003-2004
--
--- Maintainer : Isaac Jones <ijones@syntaxpolice.org>
--- Stability : alpha
+-- Maintainer : cabal-devel@haskell.org
-- Portability : portable
--
--- Explanation: Perform the \"@.\/setup register@\" action.
--- Uses a drop-file for HC-PKG. See also "Distribution.InstalledPackageInfo".
+-- This module deals with registering and unregistering packages. There are a
+-- couple ways it can do this, one is to do it directly. Another is to generate
+-- a script that can be run later to do it. The idea here being that the user
+-- is shielded from the details of what command to use for package registration
+-- for a particular compiler. In practice this aspect was not especially
+-- popular so we also provide a way to simply generate the package registration
+-- file which then must be manually passed to @ghc-pkg@. It is possible to
+-- generate registration information for where the package is to be installed,
+-- or alternatively to register the package inplace in the build tree. The
+-- latter is occasionally handy, and will become more important when we try to
+-- build multi-package systems.
+--
+-- This module does not delegate anything to the per-compiler modules but just
+-- mixes it all in in this module, which is rather unsatisfactory. The script
+-- generation and the unregister feature are not well used or tested.
{- Copyright (c) 2003-2004, Isaac Jones
All rights reserved.
diff --git a/Distribution/Simple/Setup.hs b/Distribution/Simple/Setup.hs
index dece0e47b0be400461ef88f857c517a10c6c2500..578da82f6f695d6172c47a22becb074035327d53 100644
--- a/Distribution/Simple/Setup.hs
+++ b/Distribution/Simple/Setup.hs
@@ -2,13 +2,29 @@
-- |
-- Module : Distribution.Simple.Setup
-- Copyright : Isaac Jones 2003-2004
+-- Duncan Coutts 2007
--
--- Maintainer : Isaac Jones <ijones@syntaxpolice.org>
--- Stability : alpha
+-- Maintainer : cabal-devel@haskell.org
-- Portability : portable
--
--- Explanation: Data types and parser for the standard command-line
--- setup. Will also return commands it doesn't know about.
+-- This is a big module, but not very complicated. The code is very regular
+-- and repetitive. It defines the command line interface for all the Cabal
+-- commands. For each command (like @configure@, @build@ etc) it defines a type
+-- that holds all the flags, the default set of flags and a 'CommandUI' that
+-- maps command line flags to and from the corresponding flags type.
+--
+-- All the flags types are instances of 'Monoid', see
+-- <http://www.haskell.org/pipermail/cabal-devel/2007-December/001509.html>
+-- for an explanation.
+--
+-- The types defined here get used in the front end and especially in
+-- @cabal-install@ which has to do quite a bit of manipulating sets of command
+-- line flags.
+--
+-- This is actually relatively nice, it works quite well. The main change it
+-- needs is to unify it with the code for managing sets of fields that can be
+-- read and written from files. This would allow us to save configure flags in
+-- config files.
{- All rights reserved.
diff --git a/Distribution/Simple/SetupWrapper.hs b/Distribution/Simple/SetupWrapper.hs
index 1d8bd7a761a8e23a11a98c64bd8cf501d51f506d..79094303f27b2226d12eb07dc41a4d92bbe083a2 100644
--- a/Distribution/Simple/SetupWrapper.hs
+++ b/Distribution/Simple/SetupWrapper.hs
@@ -3,8 +3,7 @@
-- Module : Distribution.SetupWrapper
-- Copyright : (c) The University of Glasgow 2006
--
--- Maintainer : http://hackage.haskell.org/trac/hackage
--- Stability : alpha
+-- Maintainer : cabal-devel@haskell.org
-- Portability : portable
--
-- The user interface to building and installing Cabal packages.
diff --git a/Distribution/Simple/SrcDist.hs b/Distribution/Simple/SrcDist.hs
index 175d965d90a70670f06dfc35989e179e3b46b780..dea206f34acd311fa19492a29aad71dbf0e139de 100644
--- a/Distribution/Simple/SrcDist.hs
+++ b/Distribution/Simple/SrcDist.hs
@@ -3,13 +3,18 @@
-- Module : Distribution.Simple.SrcDist
-- Copyright : Simon Marlow 2004
--
--- Maintainer : Isaac Jones <ijones@syntaxpolice.org>
--- Stability : alpha
+-- Maintainer : cabal-devel@haskell.org
-- Portability : portable
--
--- Implements the \"@.\/setup sdist@\" command, which creates a source
--- distribution for this package. That is, packs up the source code
--- into a tarball.
+-- This handles the @sdist@ command. The module exports an 'sdist' action but
+-- also some of the phases that make it up so that other tools can use just the
+-- bits they need. In particular the preparation of the tree of files to go
+-- into the source tarball is separated from actually building the source
+-- tarball.
+--
+-- The 'createArchive' action uses the external @tar@ program and assumes that
+-- it accepts the @-z@ flag. Neither of these assumptions are valid on Windows.
+-- The 'sdist' action now also does some distribution QA checks.
{- Copyright (c) 2003-2004, Simon Marlow
All rights reserved.
diff --git a/Distribution/Simple/UserHooks.hs b/Distribution/Simple/UserHooks.hs
index 0e7e0c8c447d319e6fb4592ee6bc3ed7a471e8e0..de05512a4aa4f47eb4bee10703c72977faac6217 100644
--- a/Distribution/Simple/UserHooks.hs
+++ b/Distribution/Simple/UserHooks.hs
@@ -3,18 +3,24 @@
-- Module : Distribution.Simple.UserHooks
-- Copyright : Isaac Jones 2003-2005
--
--- Maintainer : Isaac Jones <ijones@syntaxpolice.org>
--- Stability : alpha
+-- Maintainer : cabal-devel@haskell.org
-- Portability : portable
--
--- Explanation: Simple build system; basically the interface for
--- Distribution.Simple.\* modules. When given the parsed command-line
--- args and package information, is able to perform basic commands
--- like configure, build, install, register, etc.
+-- This defines the API that @Setup.hs@ scripts can use to customise the way
+-- the build works. This module just defines the 'UserHooks' type. The
+-- predefined sets of hooks that implement the @Simple@, @Make@ and @Configure@
+-- build systems are defined in "Distribution.Simple". The 'UserHooks' is a big
+-- record of functions. There are 3 for each action, a pre, post and the action
+-- itself. There are few other miscellaneous hooks, ones to extend the set of
+-- programs and preprocessors and one to override the function used to read the
+-- @.cabal@ file.
--
--- This module isn't called \"Simple\" because it's simple. Far from
--- it. It's called \"Simple\" because it does complicated things to
--- simple software.
+-- This hooks type is widely agreed to not be the right solution. Partly this
+-- is because changes to it usually break custom @Setup.hs@ files and yet many
+-- internal code changes do require changes to the hooks. For example we cannot
+-- pass any extra parameters to most of the functions that implement the
+-- various phases because it would involve changing the types of the
+-- corresponding hook. At some point it will have to be replaced.
{- All rights reserved.
diff --git a/Distribution/Simple/Utils.hs b/Distribution/Simple/Utils.hs
index d61f1c9d5e06563d5b3cee016a9d27147d6d5188..7edc676cb88e93f411d19f2cfffbedc7ec4a7e08 100644
--- a/Distribution/Simple/Utils.hs
+++ b/Distribution/Simple/Utils.hs
@@ -10,12 +10,14 @@
-- Copyright : Isaac Jones, Simon Marlow 2003-2004
-- portions Copyright (c) 2007, Galois Inc.
--
--- Maintainer : Isaac Jones <ijones@syntaxpolice.org>
--- Stability : alpha
+-- Maintainer : cabal-devel@haskell.org
-- Portability : portable
--
--- Explanation: Misc. Utilities, especially file-related utilities.
--- Stuff used by multiple modules that doesn't fit elsewhere.
+-- A large and somewhat miscellaneous collection of utility functions used
+-- throughout the rest of the Cabal lib and in other tools that use the Cabal
+-- lib like @cabal-install@. It has a very simple set of logging actions. It
+-- has low level functions for running programs, a bunch of wrappers for
+-- various directory and file functions that do extra logging.
{- All rights reserved.
@@ -441,8 +443,8 @@ data FileGlob
-- | No glob at all, just an ordinary file
= NoGlob FilePath
- -- | dir prefix and extension, like "foo/bar/*.baz" corresponds to
- -- @FileGlob "foo/bar" (Just ".baz")@
+ -- | dir prefix and extension, like @\"foo\/bar\/\*.baz\"@ corresponds to
+ -- @FileGlob \"foo\/bar\" (Just \".baz\")@
| FileGlob FilePath String
parseFileGlob :: FilePath -> Maybe FileGlob
diff --git a/Distribution/System.hs b/Distribution/System.hs
index 9991645dc11336a2c868dbdbbe3d5b464dd55da8..060a17f26110867ef924183c2948158afdcb8dc3 100644
--- a/Distribution/System.hs
+++ b/Distribution/System.hs
@@ -1,3 +1,18 @@
+-----------------------------------------------------------------------------
+-- |
+-- Module : Distribution.System
+-- Copyright : Duncan Coutts 2007-2008
+--
+-- Maintainer : cabal-devel@haskell.org
+-- Portability : portable
+--
+-- Cabal often needs to do slightly different things on specific platforms. You
+-- probably know about the 'System.Info.os' however using that is very
+-- inconvenient because it is a string and different Haskell implementations
+-- do not agree on using the same strings for the same platforms! (In
+-- particular see the controversy over "windows" vs "ming32"). So to make it
+-- more consistent and easy to use we have an 'OS' enumeration.
+--
module Distribution.System (
-- * Operating System
OS(..),
diff --git a/Distribution/Text.hs b/Distribution/Text.hs
index 192cab19bbcbfcd0c2eb1eb66228f08f118ba85b..298e5baf1b909dfd951c993a4219ef1c4e9ca157 100644
--- a/Distribution/Text.hs
+++ b/Distribution/Text.hs
@@ -1,3 +1,16 @@
+-----------------------------------------------------------------------------
+-- |
+-- Module : Distribution.Text
+-- Copyright : Duncan Coutts 2007
+--
+-- Maintainer : cabal-devel@haskell.org
+-- Portability : portable
+--
+-- This defines a 'Text' class which is a bit like the 'Read' and 'Show'
+-- classes. The difference is that is uses a modern pretty printer and parser
+-- system and the format is not expected to be Haskell concrete syntax but
+-- rather the external human readable representation used by Cabal.
+--
module Distribution.Text (
Text(..),
display,
diff --git a/Distribution/Verbosity.hs b/Distribution/Verbosity.hs
index e89c988afc5869e45f7b29f51277d0354ce31d90..845d79a4d97d45aa586d360b68c150a166263735 100644
--- a/Distribution/Verbosity.hs
+++ b/Distribution/Verbosity.hs
@@ -3,10 +3,13 @@
-- Module : Distribution.Verbosity
-- Copyright : Ian Lynagh 2007
--
--- Maintainer : Isaac Jones <ijones@syntaxpolice.org>
--- Stability : alpha
+-- Maintainer : cabal-devel@haskell.org
-- Portability : portable
--
+-- A simple 'Verbosity' type with associated utilities. There are 4 standard
+-- verbosity levels from 'silent', 'normal', 'verbose' up to 'deafening'. This
+-- is used for deciding what logging messages to print.
+
-- Verbosity for Cabal functions
{- Copyright (c) 2007, Ian Lynagh
diff --git a/Distribution/Version.hs b/Distribution/Version.hs
index c34a2ba05ecaf43c99c8513fe57250ad0a9234a4..ca69d6e23d6e8d66d41ff291ec4e1586e380cbdb 100644
--- a/Distribution/Version.hs
+++ b/Distribution/Version.hs
@@ -3,11 +3,12 @@
-- Module : Distribution.Version
-- Copyright : Isaac Jones, Simon Marlow 2003-2004
--
--- Maintainer : Isaac Jones <ijones@syntaxpolice.org>
--- Stability : alpha
+-- Maintainer : cabal-devel@haskell.org
-- Portability : portable
--
--- Versions for packages, based on the 'Version' datatype.
+-- Exports the 'Version' type along with a parser and pretty printer. A version
+-- is something like @\"1.3.3\"@. It also defines the 'VersionRange' data
+-- types. Version ranges are like @\">= 1.2 && < 2\"@.
{- Copyright (c) 2003-2004, Isaac Jones
All rights reserved.
diff --git a/Language/Haskell/Extension.hs b/Language/Haskell/Extension.hs
index 63d56c52f18d53a948b4c5ae86a63efb901b2dce..a31cd7441cb86eb2e83773dc9f583e3edf1e043d 100644
--- a/Language/Haskell/Extension.hs
+++ b/Language/Haskell/Extension.hs
@@ -3,8 +3,7 @@
-- Module : Language.Haskell.Extension
-- Copyright : Isaac Jones 2003-2004
--
--- Maintainer : Isaac Jones <ijones@syntaxpolice.org>
--- Stability : alpha
+-- Maintainer : libraries@haskell.org
-- Portability : portable
--
-- Haskell language extensions