[GHC] #839: Generate documentation for built-in types and functions

[GHC]

#839: Generate documentation for built-in types and functions
-----------------------+----------------------------------------------------
  Reporter:  simonpj   |          Owner:         
      Type:  task      |         Status:  new    
  Priority:  normal    |      Milestone:         
 Component:  Compiler  |        Version:  6.4.2  
  Severity:  normal    |     Resolution:         
  Keywords:            |             Os:  Unknown
Difficulty:  Unknown   |   Architecture:  Unknown
-----------------------+----------------------------------------------------
Changes (by simonpj):

  * summary:  Generate documentation for built-in functiuons => Generate
              documentation for built-in types and functions

Old description:

> 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.

New description:

 GHC has a bunch of primitive types, which are not definable in Haskell,
 such as
   * Int#, Float#, Double# etc
   * ByteArray#
   * etc
 They are defined in `TysPrim` but nowhere documented.

 GHC also 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].

 However, '''both the primitive types, and these built-in functions, 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 types and 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