[GHC] #839: Generate documentation for built-in functiuons

[GHC]

#839: Generate documentation for built-in functiuons
-------------------------+--------------------------------------------------
    Reporter:  simonpj   |        Owner:         
        Type:  task      |       Status:  new    
    Priority:  normal    |    Milestone:         
   Component:  Compiler  |      Version:  6.4.2  
    Severity:  normal    |     Keywords:         
          Os:  Unknown   |   Difficulty:  Unknown
Architecture:  Unknown   |  
-------------------------+--------------------------------------------------
GHC has a handful of built-in functions, that are
   * Not primops
   * Are not definable in Haskell
   * But are definable in Core
   * Are defined in the compiler itself, in basicTypes/MkId.lhs
   * Come from the pseudo-module {{{GHC.Prim}}}, like primops and primitive
 types.
 The examples I can think of are
   * unsafeCoerce
   * inline
   * lazy
 Currently they are documented in the
 [http://www.haskell.org/ghc/dist/current/docs/users_guide/special-ids.html
 (HEAD) user manual], but they are invisible to Haddock, and hence do not
 appear in the online Haddock documentation.  This is bad.

 You might think that the same would be true of the primitive operations
 (primops).  However, the primops are described by a text file
 {{{prelude/primops.txt.pp}}, and there's a preprocessor
 ({{{utils/genprimopcode}}}) that generates the base-package pseudo-module
 {{{GHC/Prim.hs}}} from the text file.  This pseudo-module is not compiled;
 but it ''is'' given to Haddock, and that's how the primops appear in the
 Haddock docs.

 So the task is to add a bit of extra markup syntax to {{{primops.txt.pp}}}
 so that it can describe these special built-in functions, and inject their
 type signatures and documentation into {{{GHC/Prim.hs}}}, so that Haddock
 can see it.  Not a huge task.

 Thanks to Neil Mitchell for pointing out the difficulty.

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