[commit: ghc] ghc-8.2: Document the perplexing reversed nature of extraPkgConfs and friends. (24910e1)

[git at git.haskell.org]

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

On branch  : ghc-8.2
Link       : http://ghc.haskell.org/trac/ghc/changeset/24910e1940f5823c515810b859da709fb647e739/ghc

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

commit 24910e1940f5823c515810b859da709fb647e739
Author: Edward Z. Yang <ezyang at cs.stanford.edu>
Date:   Sun Mar 19 16:06:55 2017 -0700

    Document the perplexing reversed nature of extraPkgConfs and friends.
    
    Signed-off-by: Edward Z. Yang <ezyang at cs.stanford.edu>
    (cherry picked from commit 40b65db4cd34c3566b9f6c53c086d53e97574217)


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

24910e1940f5823c515810b859da709fb647e739
 compiler/main/DynFlags.hs | 20 +++++++++++++++-----
 1 file changed, 15 insertions(+), 5 deletions(-)

diff --git a/compiler/main/DynFlags.hs b/compiler/main/DynFlags.hs
index f48e99e..99a41d9 100644
--- a/compiler/main/DynFlags.hs
+++ b/compiler/main/DynFlags.hs
@@ -806,16 +806,26 @@ data DynFlags = DynFlags {
   --  Package flags
   extraPkgConfs         :: [PkgConfRef] -> [PkgConfRef],
         -- ^ The @-package-db@ flags given on the command line, in the order
-        -- they appeared.
+        -- they appeared.  In *reverse* order that they're specified
+        -- on the command line.  This is intended to be applied with the
+        -- list of "initial" package databases derived from @GHC_PACKAGE_PATH@;
+        -- see 'getPackageConfRefs'; this is a function because 'extraPkgConfs'
+        -- maybe configured to filter out certain flags from *either* the
+        -- user command line, or the base command; see for example
+        -- 'removeUserPkgConf'.
 
   ignorePackageFlags    :: [IgnorePackageFlag],
-        -- ^ The @-ignore-package@ flags from the command line
+        -- ^ The @-ignore-package@ flags from the command line.
+        -- In *reverse* order that they're specified on the command line.
   packageFlags          :: [PackageFlag],
-        -- ^ The @-package@ and @-hide-package@ flags from the command-line
+        -- ^ The @-package@ and @-hide-package@ flags from the command-line.
+        -- In *reverse* order that they're specified on the command line.
   pluginPackageFlags    :: [PackageFlag],
-        -- ^ The @-plugin-package-id@ flags from command line
+        -- ^ The @-plugin-package-id@ flags from command line.
+        -- In *reverse* order that they're specified on the command line.
   trustFlags            :: [TrustFlag],
-        -- ^ The @-trust@ and @-distrust@ flags
+        -- ^ The @-trust@ and @-distrust@ flags.
+        -- In *reverse* order that they're specified on the command line.
   packageEnv            :: Maybe FilePath,
         -- ^ Filepath to the package environment file (if overriding default)