Add comments to darcs-all and packages

darcs-all

@@ -22,6 +22,24 @@ use strict;
 #      ./darc-all push --dry-run
 #          To see what local patches you have relative to the main repos
 #
+# -------------- Flags -------------------
+#   -q says to be quite, and -s to be silent.
+#
+#   -i says to ignore darcs errors and move on to the next repository
+#
+#   -r repo says to use repo as the location of package repositories
+#
+#   --checked-out says that the remote repo is in checked-out layout, as
+#   opposed to the layout used for the main repo.  By default a repo on
+#   the local filesystem is assumed to be checked-out, and repos accessed
+#   via HTTP or SSH are assumed to be in the main repo layout; use
+#   --checked-out to override the latter.
+#
+#   --nofib, --testsuite also get the nofib and testsuite repos respectively
+#
+#   The darcs get flag you are most likely to want is --complete. By
+#   default we pass darcs the --partial flag.
+#
 # ------------ Which repos to use -------------
 # darcs-all uses the following algorithm to decide which remote repos to use
 #
@@ -52,24 +70,6 @@ use strict;
 # root one.  So the remote repos must be laid out in one of the two
 # formats given by <local-path> and <remote-path> in the file 'packages'.
 
-# -------------- Flags -------------------
-#   -q says to be quite, and -s to be silent.
-#
-#   -i says to ignore darcs errors and move on to the next repository
-#
-#   -r repo says to use repo as the location of package repositories
-#
-#   --checked-out says that the remote repo is in checked-out layout, as
-#   opposed to the layout used for the main repo.  By default a repo on
-#   the local filesystem is assumed to be checked-out, and repos accessed
-#   via HTTP or SSH are assumed to be in the main repo layout; use
-#   --checked-out to override the latter.
-#
-#   --nofib, --testsuite also get the nofib and testsuite repos respectively
-#
-#   The darcs get flag you are most likely to want is --complete. By
-#   default we pass darcs the --partial flag.
-#
 
 $| = 1; # autoflush stdout after each print, to avoid output after die
 

packages

-# 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"