[GHC] #11584: [Template Haskell] Language.Haskell.TH.Syntax.hs contains misleading comment

[GHC]

#11584: [Template Haskell] Language.Haskell.TH.Syntax.hs contains misleading
comment
-------------------------------------+-------------------------------------
           Reporter:  bollmann       |             Owner:  bollmann
               Type:  bug            |            Status:  new
           Priority:  normal         |         Milestone:
          Component:  Template       |           Version:  7.10.3
  Haskell                            |
           Keywords:  newcomer       |  Operating System:  Unknown/Multiple
       Architecture:                 |   Type of failure:  Documentation
  Unknown/Multiple                   |  bug
          Test Case:                 |        Blocked By:
           Blocking:                 |   Related Tickets:
Differential Rev(s):                 |         Wiki Page:
-------------------------------------+-------------------------------------
 In `Language.Haskell.TH.Syntax` it reads on the generation of fresh names:

 {{{

 Although names generated by @newName@ cannot /be captured/, they can
 /capture/ other names. For example, this:

 >g = $(do
 >  nm1 <- newName "x"
 >  let nm2 = mkName "x"
 >  return (LamE [VarP nm2] (LamE [VarP nm1] (VarE nm2)))
 > )

 will produce the splice

 >g = \x -> \x0 -> x0

 since the occurrence @VarE nm2@ is captured by the innermost binding
 of @x@, namely @VarP nm1 at .
 }}}

 I find this note quite misleading, especially since the above splice
 normally generates something like

 {{{
 \ x -> \ x_a3vv -> x
 }}}

 where no inadvertent capture occurs.

 I belive this note should rather be something as follows:

 {{{

 Although names generated by @newName@ cannot /be captured/, they can
 /capture/ other names. For example, suppose that the next invocation
 of newName would generate the name nm1 = x0, and we have the
 following splice, where mkName uses the very same name x0 for
 nm2:

 >g = $(do
 >  nm1 <- newName "x"
 >  let nm2 = mkName "x0"
 >  return (LamE [VarP nm2] (LamE [VarP nm1] (VarE nm2)))
 > )

 This will produce the following splice, where nm1 generated by newName
 captures nm2 assigned by mkName:

 >g = \x0 -> \x0 -> x0

 In particular, now the occurrence @VarE nm2@ is captured by @VarP nm1@
 and not by @VarP nm2" anymore (as was intended by the TH AST).

 }}}

 I'm happy to change this, if people agree :-).

--
Ticket URL: <http://ghc.haskell.org/trac/ghc/ticket/11584>
GHC <http://www.haskell.org/ghc/>
The Glasgow Haskell Compiler