Add comments to darcs-all and packages

1 files changed, 19 insertions, 5 deletions

diff --git a/packages b/packages
index f6361975ab..6550c0cb70 100644
--- a/packages
+++ b/packages
@@ -1,14 +1,28 @@
-# Note that when adding libraries to this file, you also need to add
+# Despite the name "package", this file contains the master list of 
+# the *repositories* that make up GHC.
+#
+# Some of this information is duplicated elsewhere in the build system:
+#    See Trac #3896
+# In particular when adding libraries to this file, you also need to add
 # the library to the SUBDIRS variable in libraries/Makefile so that they
 # actually get built
 #
+# The repos are of several kinds:
+#    - The main GHC source repo
+#    - Each boot package lives in a repo
+#    - DPH is a repo that contains several packages
+#    - Haddock and hsc2hs are applications, built on top of GHC, 
+#        and in turn needed to bootstrap GHC
+#    - ghc-tarballs is need to build GHC
+#    - nofib and testsuite are optional helpers
+#
 # The format of the lines in this file is:
 #   localpath    (optional) tag    remotepath    VCS
 # where
-#   * localpath is where to put the repository in a checked out tree,
-#   * remotepath is where the repository is in the central repository,
-#   * VCS is what version control system the repo uses,
-#   * the tag, is present, determines when "darcs-all get" will get the
+#   * 'localpath' is where to put the repository in a checked out tree,
+#   * 'remotepath' is where the repository is in the central repository,
+#   * 'VCS' is what version control system the repo uses,
+#   * The 'tag', if present, determines when "darcs-all get" will get the
 #     repo. If there is no tag then it will always get it, but if there
 #     is a tag then a corresponding flag must be given to darcs-all, e.g.
 #     if you want to get the packages with an "extralibs" or "testsuite"