Documentation for GHC primops

Simon Peyton-Jones simonpj at microsoft.com
Wed Jun 29 09:38:53 EDT 2005


Dear GHC users

This message is a request for help with a well-contained task that will
improve GHC's Haddock documentation.

GHC provides lots of primitive operations.  They are described in a
single ASCII files primpos.txt.pp; the description in that file gives
types and English-language descriptions, as well as some other GHC-ish
information.

This description file is chomped up by a pre-processor (genprimopcode),
which produces either 

	(a) Haskell source code for data types describing 
	the primops [these modules become part of GHC itself), or

	(b) Latex stuff which can be part of a document.  
	You can see the output in Section 4.4 of the External 
	Core document
(http://www.haskell.org/ghc/docs/papers/core.ps.gz)

However, there's no Haddock document describing all these primops!!
Although they are all available through the module GHC.Exts, the Haddock
documentation for GHC.Exts says nothing at all about them.
http://www.haskell.org/ghc/docs/latest/html/libraries/base/GHC.Exts.html
Reason: there is no Haskell source code for GHC.Prim, the pseudo-module
that exports all the primops.

What we want is to generate GHC.Prim.hs from primops.txt.pp.  This .hs
file would not be fed to GHC; rather it'd just be there so that Haddock
could see it.  For example:

	module GHC.Prim( ...list all primops... ) where

	(+#) :: Int# -> Int# -> Int#
	--| Adds two unboxed Ints

	...etc...

you get the idea.  No Haskell code, only type signatures.



Would someone cares to write this new backend to "genprimopcode".  The
latter is a Haskell program that can parse primops.txt.pp, and already
has two back ends (a) and (b) above.  What we want is to add (c)
generate Haskell that Haddock can understand.

Note that the documentation itself is already written -- it's in
primpos.txt.pp.  That's what's so tantalising.  All that we need is to
mangle it into Haddock.  


Any volunteers?  It doesn't involve touching GHC itself.
"gemprimopcode" is a completely standalone Haskell program, currently
some 730 lines long. 

Simon


More information about the Glasgow-haskell-users mailing list