Better document "build-tools" and "build-tool-depends"

Cabal/Distribution/Types/BuildInfo.hs

@@ -30,8 +30,23 @@ import Language.Haskell.Extension
 -- Consider refactoring into executable and library versions.
 data BuildInfo = BuildInfo {
         buildable         :: Bool,      -- ^ component is buildable here
-        buildTools        :: [LegacyExeDependency], -- ^ tools needed to build this bit
-        toolDepends       :: [ExeDependency], -- ^ haskell tools needed to build this bit
+        -- | Tools needed to build this bit.
+        --
+        -- This is a legacy field that "build-tool-depends" larely supersedes.
+        --
+        -- Unless use are very sure what you are doing, use the functions in
+        -- `Distribution.Simple.BuildToolDepends` rather than accessing this
+        -- field directly.
+        buildTools        :: [LegacyExeDependency],
+        -- | Haskell tools needed to build this bit
+        --
+        -- This field is better than "build-tools" because it allows one to
+        -- precisely specify an executable in a package.
+        --
+        -- Unless use are very sure what you are doing, use the functions in
+        -- `Distribution.Simple.BuildToolDepends` rather than accessing this
+        -- field directly.
+        toolDepends       :: [ExeDependency],
         cppOptions        :: [String],  -- ^ options for pre-processing Haskell code
         ccOptions         :: [String],  -- ^ options for C compiler
         ldOptions         :: [String],  -- ^ options for linker
@@ -180,4 +195,3 @@ lookupHcOptions :: (BuildInfo -> [(CompilerFlavor,[String])])
 lookupHcOptions f hc bi = [ opt | (hc',opts) <- f bi
                           , hc' == hc
                           , opt <- opts ]
-