[commit: ghc] wip/nfs-locking: Comments (b91d515)

[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/b91d5152c1979d7c36cb2ab16821abec8da7ec1c/ghc

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

commit b91d5152c1979d7c36cb2ab16821abec8da7ec1c
Author: Andrey Mokhov <andrey.mokhov at gmail.com>
Date:   Sun May 15 00:03:12 2016 +0100

    Comments
    
    [skip ci]


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

b91d5152c1979d7c36cb2ab16821abec8da7ec1c
 src/Settings/User.hs | 38 +++++++++++++++++++++-----------------
 1 file changed, 21 insertions(+), 17 deletions(-)

diff --git a/src/Settings/User.hs b/src/Settings/User.hs
index 2294fc7..7cf9997 100644
--- a/src/Settings/User.hs
+++ b/src/Settings/User.hs
@@ -12,40 +12,44 @@ import Expression
 import Predicates
 import Settings.Default
 
--- | All build artefacts are stored in 'buildRootPath' directory.
+-- See doc/user-settings.md for instructions.
+
+-- | All build results are put into 'buildRootPath' directory.
 buildRootPath :: FilePath
 buildRootPath = "_build"
 
--- | Control user-specific command line arguments.
+-- | Modify default build command line arguments.
 userArgs :: Args
 userArgs = builder Ghc ? remove ["-Wall", "-fwarn-tabs"]
 
--- | Control which packages get to be built.
+-- | Modify the set of packages that are built by default in each stage.
 userPackages :: Packages
 userPackages = mempty
 
--- | Add new user-defined packages.
+-- | Add user defined packages. Don't forget to add them to 'userPackages' too.
 userKnownPackages :: [Package]
 userKnownPackages = []
 
--- | Choose the integer library: integerGmp or integerSimple.
+-- | Choose the integer library: 'integerGmp' or 'integerSimple'.
 integerLibrary :: Package
 integerLibrary = integerGmp
 
--- | Control which ways library packages are built.
--- FIXME: skip dynamic since it's currently broken #4
+-- FIXME: We skip 'dynamic' since it's currently broken #4.
+-- | Modify the set of ways in which library packages are built.
 userLibraryWays :: Ways
 userLibraryWays = remove [dynamic]
 
--- | Control which ways the 'rts' package is built.
+-- | Modify the set of ways in which the 'rts' package is built.
 userRtsWays :: Ways
 userRtsWays = mempty
 
--- | User-defined flags. Note the following type semantics:
--- * Bool: a plain Boolean flag whose value is known at compile time
--- * Action Bool: a flag whose value can depend on the build environment
--- * Predicate: a flag depending on the build environment and the current target
+-- | User defined flags. Note the following type semantics:
+-- * @Bool@: a plain Boolean flag whose value is known at compile time.
+-- * @Action Bool@: a flag whose value can depend on the build environment.
+-- * @Predicate@: a flag whose value can depend on the build environment and
+-- on the current build target.
 
+-- TODO: Drop 'trackBuildSystem' as it brings negligible gains.
 -- | Set this to True if you are making any changes in the build system and want
 -- appropriate rebuilds to be initiated. Switching this to False speeds things
 -- up a little (particularly zero builds).
@@ -62,12 +66,12 @@ validating = False
 splitObjects :: Predicate
 splitObjects = (return cmdSplitObjects) &&^ defaultSplitObjects
 
--- | Control when to build documentation.
+-- | Control when to build Haddock documentation.
 buildHaddock :: Predicate
 buildHaddock = return cmdBuildHaddock
 
 -- TODO: Do we need to be able to set these from command line?
--- TODO: Turn below into ghcWays?
+-- TODO: Turn the flags below into a simple list @ghcWays :: [Way]@?
 dynamicGhcPrograms :: Bool
 dynamicGhcPrograms = False
 
@@ -81,12 +85,12 @@ ghcDebugged :: Bool
 ghcDebugged = False
 
 -- | Set to True to print full command lines during the build process. Note,
--- this is a Predicate, hence you can enable verbose output for a chosen package
--- only, e.g.: verboseCommands = package ghcPrim.
+-- this is a Predicate, hence you can enable verbose output only for certain
+-- targets, e.g.: @verboseCommands = package ghcPrim at .
 verboseCommands :: Predicate
 verboseCommands = return False
 
--- TODO: Replace with stage2 ? arg "-Werror"?
+-- TODO: Replace with stage2 ? arg "-Werror"? Also see #251.
 -- | To enable -Werror in Stage2 set turnWarningsIntoErrors = stage2.
 turnWarningsIntoErrors :: Predicate
 turnWarningsIntoErrors = return False