id,summary,reporter,owner,description,type,status,priority,milestone,component,version,resolution,keywords,cc,os,architecture,failure,testcase,blockedby,blocking,related,differential
839,Generate documentation for built-in types and primitve operations,simonpj,igloo,"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.",merge,closed,normal,6.6.1,Documentation,6.4.2,fixed,,,Unknown/Multiple,Unknown/Multiple,,N/A,,,,