Documenting GHC

[Simon Marlow]

On 14/03/2010 07:50, Yitzchak Gale wrote:
> In the thread "strictness of unused arguments",
> Max Bolingbroke wrote:
>> There is nothing *published* (Simon has a half-written one lying
>> around though)...
>> Unfortunately the weird behaviour you are seeing is due to...
>> one of the unpublished bits...
>
> There are various critical parts of the inner workings of GHC
> that are poorly understood outside of the GHC team.
> Strictness analysis and other optimizations, and the syntax
> and semantics of GHC Core, immediately come to my mind.
> There is much more.
>
> As a user of GHC, I would vote for a full two-month delay in
> the next release of GHC to allow the GHC team to devote
> two months of their time exclusively to writing documentation.

While it would be lovely to be able to do that, in reality both Simon PJ 
and myself work in a research lab and it would be hard for us to take 
two months out to write compiler internals documentation.  We try to 
write docs when we can, e.g. I recently wrote a bunch of stuff about the 
GC internals on the wiki:

http://hackage.haskell.org/trac/ghc/wiki/Commentary/Rts/Storage/GC

As I implement things, I try to document them in the commentary. 
Another good example of some internal docs that I wrote recently is the 
recompilation avoidance algorithm:

http://hackage.haskell.org/trac/ghc/wiki/Commentary/Compiler/RecompilationAvoidance

So over time, the docs gradually get better.  I'd like to encourage 
others looking at the sources to help us do this too, and to go through 
the existing docs to update them, make sure they're properly 
cross-linked, and so on.

Cheers,
	Simon