Generate documentation for built-in types and primitve operations

[simonpj]

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

[simonmar]

Fixed, thanks to Dinko Tenev for the patch. To merge:

Wed Feb 28 16:34:42 GMT 2007  Simon Marlow <simonmar@microsoft.com>
  * Fix #839 (Generate documentation for built-in types and primitve operations

[igloo]

Merged.