From 0c993c8402802593e82f6158af03ca67c64dfed9 Mon Sep 17 00:00:00 2001
From: Duncan Coutts <duncan@haskell.org>
Date: Sat, 28 Jun 2008 17:25:50 +0000
Subject: [PATCH] Update module headers Use cabal-devel@haskell.org as the
maintainer in most cases except for a few which were pre-existing modules
copied from elsewhere or modules like L.H.Extension which really belong to
libraries@haskell.org Remove the useless stability module. We have more
detailed information on stability elsewhere (in the version number and user
guide). Add more top level module documentation, taken from the source guide.
---
Distribution/Compat/ReadP.hs | 1 -
Distribution/Compiler.hs | 18 +++++++++--
Distribution/GetOpt.hs | 1 -
Distribution/InstalledPackageInfo.hs | 13 ++++++--
Distribution/License.hs | 13 ++++----
Distribution/Make.hs | 12 +++++--
Distribution/ModuleName.hs | 5 ++-
Distribution/Package.hs | 8 +++--
Distribution/PackageDescription.hs | 16 ++++++++--
Distribution/PackageDescription/Check.hs | 16 ++++++++--
.../PackageDescription/Configuration.hs | 9 ++++--
Distribution/PackageDescription/Parse.hs | 8 +++--
Distribution/ParseUtils.hs | 13 +++++---
Distribution/ReadE.hs | 3 +-
Distribution/Simple.hs | 20 ++++++++----
Distribution/Simple/Build.hs | 19 +++++++++---
Distribution/Simple/BuildPaths.hs | 3 +-
Distribution/Simple/Command.hs | 12 ++++---
Distribution/Simple/Compiler.hs | 14 +++++++--
Distribution/Simple/Configure.hs | 18 ++++++++---
Distribution/Simple/GHC.hs | 31 ++++++++++++++++---
Distribution/Simple/GHC/IPI641.hs | 3 +-
Distribution/Simple/GHC/IPI642.hs | 3 +-
Distribution/Simple/Haddock.hs | 15 ++++++---
Distribution/Simple/Hugs.hs | 6 ++--
Distribution/Simple/Install.hs | 10 +++---
Distribution/Simple/InstallDirs.hs | 16 +++++-----
Distribution/Simple/JHC.hs | 6 ++--
Distribution/Simple/LocalBuildInfo.hs | 15 ++++-----
Distribution/Simple/NHC.hs | 5 +--
Distribution/Simple/PackageIndex.hs | 6 ++--
Distribution/Simple/PackageSet.hs | 8 ++---
Distribution/Simple/PreProcess.hs | 21 +++++++------
Distribution/Simple/PreProcess/Unlit.hs | 3 +-
Distribution/Simple/Program.hs | 20 +++++++++---
Distribution/Simple/Register.hs | 20 +++++++++---
Distribution/Simple/Setup.hs | 24 +++++++++++---
Distribution/Simple/SetupWrapper.hs | 3 +-
Distribution/Simple/SrcDist.hs | 15 ++++++---
Distribution/Simple/UserHooks.hs | 24 ++++++++------
Distribution/Simple/Utils.hs | 14 +++++----
Distribution/System.hs | 15 +++++++++
Distribution/Text.hs | 13 ++++++++
Distribution/Verbosity.hs | 7 +++--
Distribution/Version.hs | 7 +++--
Language/Haskell/Extension.hs | 3 +-
46 files changed, 369 insertions(+), 166 deletions(-)
diff --git a/Distribution/Compat/ReadP.hs b/Distribution/Compat/ReadP.hs
index 582f4bc40d..e6450af063 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 97af9a096d..58381e389d 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 cb41692d22..b35d64fab4 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 d6c784036b..8fd9d9ad3e 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 9d0349f63d..dc21907e5e 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 931fac7bee..b103e91a82 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 9967d75f6b..3adc0c478d 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 9674f1ff69..f303eada95 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 c161ebc6d7..48f79e0f93 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 5231c7c9fe..e0c965b154 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 d8c39653e3..4ab93a17f0 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 7340fd3db7..21f9cd222b 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 f3b3ada846..3f7f04a55d 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 d0bcf13cb3..01069f673a 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 48f281a2b3..68ee477909 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 5396f68f6b..14a0e964ba 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 eb618646b6..8fd09d4640 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 66b21867ba..62cda027f5 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 5657f070b2..75cad05378 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 a0c9833847..6de712f720 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 538067708b..10e3f399b9 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 210ca1ac44..3bbe8cac2d 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 30e5a51a6b..01200591e2 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 33ee772391..2fa8922a8a 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 c9ceb12087..5130ab7691 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 7c1adb2d76..1a209d47de 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 06800aad21..11aff595e2 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 b50e0e6da1..91ac0daa54 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 1e4bf21e8d..04812ea40b 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 b39821c363..0f1131417c 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 f539b7cf37..bd2aab4b8d 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 9a7e43d59e..d74e87d49d 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 bbefdba07c..3e3e96f099 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 b30e2b3c04..891ac586aa 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 86c127c72b..4467d8befe 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 036c0b3896..8a887d8c2c 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 dece0e47b0..578da82f6f 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 1d8bd7a761..79094303f2 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 175d965d90..dea206f34a 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 0e7e0c8c44..de05512a4a 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 d61f1c9d5e..7edc676cb8 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 9991645dc1..060a17f261 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 192cab19bb..298e5baf1b 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 e89c988afc..845d79a4d9 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 c34a2ba05e..ca69d6e23d 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 63d56c52f1..a31cd7441c 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
--
GitLab