[GHC] #8864: Document heap allocation functions in StgCmmMonad/StgCmmLayout

[GHC]

#8864: Document heap allocation functions in StgCmmMonad/StgCmmLayout
------------------------------------+-------------------------------------
       Reporter:  tibbe             |             Owner:
           Type:  feature request   |            Status:  new
       Priority:  normal            |         Milestone:
      Component:  Documentation     |           Version:  7.6.3
       Keywords:                    |  Operating System:  Unknown/Multiple
   Architecture:  Unknown/Multiple  |   Type of failure:  None/Unknown
     Difficulty:  Unknown           |         Test Case:
     Blocked By:                    |          Blocking:
Related Tickets:                    |
------------------------------------+-------------------------------------
 I'm having a hard time using the heap allocation functions in
 `StgCmmMonad` and `StgCmmLayout`, as they lack documentation. I'd be very
 grateful if someone could at least document:

  * `getHpRelOffset`
  * `setVirtHp`
  * `getVirtHp`

 To get an idea which questions I'm struggling with, I need to e.g.
 understand if the value returned by `getHpRelOffset` is affected by later
 calls to `setVirtHp`. This is probably obvious to some, but reading the
 code alone is not enough to get a good understanding how all the heap
 allocation code hangs together.

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