[commit: ghc] master: Comments only (2209d5e)

[git at git.haskell.org]

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

On branch  : master
Link       : http://ghc.haskell.org/trac/ghc/changeset/2209d5e644b28f614c876b95ac5c627eb5a81fa2/ghc

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

commit 2209d5e644b28f614c876b95ac5c627eb5a81fa2
Author: Simon Peyton Jones <simonpj at microsoft.com>
Date:   Fri Mar 10 14:40:25 2017 +0000

    Comments only


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

2209d5e644b28f614c876b95ac5c627eb5a81fa2
 libraries/base/GHC/Base.hs | 53 +++++++++++++++++++++++++++++-----------------
 libraries/base/GHC/List.hs |  5 +----
 2 files changed, 35 insertions(+), 23 deletions(-)

diff --git a/libraries/base/GHC/Base.hs b/libraries/base/GHC/Base.hs
index a678c22..8548da6 100644
--- a/libraries/base/GHC/Base.hs
+++ b/libraries/base/GHC/Base.hs
@@ -951,25 +951,40 @@ mapFB ::  (elt -> lst -> lst) -> (a -> elt) -> a -> lst -> lst
 {-# INLINE [0] mapFB #-} -- See Note [Inline FB functions] in GHC.List
 mapFB c f = \x ys -> c (f x) ys
 
--- The rules for map work like this.
---
--- Up to (but not including) phase 1, we use the "map" rule to
--- rewrite all saturated applications of map with its build/fold
--- form, hoping for fusion to happen.
--- In phase 1 and 0, we switch off that rule, inline build, and
--- switch on the "mapList" rule, which rewrites the foldr/mapFB
--- thing back into plain map.
---
--- It's important that these two rules aren't both active at once
--- (along with build's unfolding) else we'd get an infinite loop
--- in the rules.  Hence the activation control below.
---
--- This same pattern is followed by many other functions:
--- e.g. append, filter, iterate, repeat, etc.
---
--- The "mapFB" rule optimises compositions of map and
--- the "mapFB/id" rule get rids of 'map id' calls.
--- (Any similarity to the Functor laws for [] is expected.)
+{- Note [The rules for map]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The rules for map work like this.
+
+* Up to (but not including) phase 1, we use the "map" rule to
+  rewrite all saturated applications of map with its build/fold
+  form, hoping for fusion to happen.
+
+  In phase 1 and 0, we switch off that rule, inline build, and
+  switch on the "mapList" rule, which rewrites the foldr/mapFB
+  thing back into plain map.
+
+  It's important that these two rules aren't both active at once
+  (along with build's unfolding) else we'd get an infinite loop
+  in the rules.  Hence the activation control below.
+
+* This same pattern is followed by many other functions:
+  e.g. append, filter, iterate, repeat, etc. in GHC.List
+
+  See also Note [Inline FB functions] in GHC.List
+
+* The "mapFB" rule optimises compositions of map
+
+* The "mapFB/id" rule get rids of 'map id' calls.
+  You might think that (mapFB c id) will turn into c simply
+  when mapFB is inlined; but before that happens the "mapList"
+  rule turns
+     (foldr (mapFB (:) id) [] a
+  back into
+     map id
+  Which is not very cleveer.
+
+* Any similarity to the Functor laws for [] is expected.
+-}
 
 {-# RULES
 "map"       [~1] forall f xs.   map f xs                = build (\c n -> foldr (mapFB c f) n xs)
diff --git a/libraries/base/GHC/List.hs b/libraries/base/GHC/List.hs
index 3eab407..018c0a7 100644
--- a/libraries/base/GHC/List.hs
+++ b/libraries/base/GHC/List.hs
@@ -203,13 +203,10 @@ We hope that one of the two measure kick in:
      in CoreArity.
 
 The oneShot annotations used in this module are correct, as we only use them in
-argumets to foldr, where we know how the arguments are called.
--}
+arguments to foldr, where we know how the arguments are called.
 
-{-
 Note [Inline FB functions]
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
-
 After fusion rules successfully fire, we are usually left with one or more calls
 to list-producing functions abstracted over cons and nil. Here we call them
 FB functions because their names usually end with 'FB'. It's a good idea to