[commit: ghc] wip/nfs-locking: Explain stages (bee9cee)

[git at git.haskell.org]

Repository : ssh://git@git.haskell.org/ghc

On branch  : wip/nfs-locking
Link       : http://ghc.haskell.org/trac/ghc/changeset/bee9ceed2f9e196b1d7adcc02c74246ec8c89f82/ghc

>---------------------------------------------------------------

commit bee9ceed2f9e196b1d7adcc02c74246ec8c89f82
Author: David Luposchainsky <dluposchainsky at gmail.com>
Date:   Wed Jan 6 15:05:37 2016 +0100

    Explain stages


>---------------------------------------------------------------

bee9ceed2f9e196b1d7adcc02c74246ec8c89f82
 src/Stage.hs | 19 ++++++++++++++++++-
 1 file changed, 18 insertions(+), 1 deletion(-)

diff --git a/src/Stage.hs b/src/Stage.hs
index 144aa29..2e581c4 100644
--- a/src/Stage.hs
+++ b/src/Stage.hs
@@ -4,10 +4,27 @@ module Stage (Stage (..), stageString) where
 import Development.Shake.Classes
 import GHC.Generics (Generic)
 
--- TODO: explain stages
+-- | A stage refers to a certain compiler in GHC's build process.
+--
+-- * Stage 0 is the bootstrapping compiler, i.e. the one already installed on
+--   the user's system.
+--
+-- * Stage 1 is built using the stage 0 compiler, using GHC's source code.
+--   The result is a compiler that was built by the bootstrapping compiler,
+--   with all the features of the new compiler.
+--
+-- * Stage 2 is built using the stage 1 compiler and GHC's source code. The
+--   result is a compiler "built by itself", commonly referred to as
+--   /bootstrapping/.
+--
+-- * Stage 3 uses stage 2 to build from source again. The result should have
+--   the same object code as stage 2, which is a good test for the compiler.
+--   Since it serves no other purpose than that, the stage 3 build is usually
+--   omitted in the build process.
 data Stage = Stage0 | Stage1 | Stage2 | Stage3
            deriving (Show, Eq, Ord, Enum, Generic)
 
+-- | Prettyprint a 'Stage'.
 stageString :: Stage -> String
 stageString stage = "stage" ++ show (fromEnum stage)