Glossary (Was: Re: "Documentation by paper")

[Joern Rennecke <joern dot rennecke at superh dot com>]

Robert Dewar:
> > There's something very wrong here. It is essential that documentation
> > be written as the code is produced, or where feasible *before* the

I disagree with that; when you are still changing the code rapidly, e.g.
because you need to do some experimenting to see what kinds of
transformations make good optimizations on average, documenting too early
can easily lead to having outdated documentation.  Just documenting what
is non-obvious to you is enough as long as you work on the code alone, and
then you can fill in the misssing bits in what is left of the code by the
time you make it ready to submission for review.

Michael Matz:
> This is all nice and fine.  I think you just want to discuss for the sake
> of discussion, because otherwise you would realize that this is all
> already after the fact.  We _have_ code which Kenner thinks is not
> documented very well (the only prove being that he hadn't heard of

I think he made a pretty good case that a glossary would be very useful.
Let's just add terms as we come across them and then have somebody who
knows supply a definition.

basic block (backend):
 A sequence of linearily executed instructions.
 Starts with the function start or a label.
 Ends with a jump instruction, a nonreturn call, with a call instruction that
 can throw an exception that is caught in the same function, before a label,
 or at function end.

basic block (frontend):
 A sequence of linearily executed instructions.
 ??? how is this different from a backend basic block

dominator:
[from dominance.c]
   A basic block D is said
   to dominate another block X, when all paths from the entry node of the CFG
   to X go also over D.  The dominance relation is a transitive reflexive
   relation and its minimal transitive reduction is a tree, called the
   dominator tree.  So for each block X besides the entry block exists a
   block I(X), called the immediate dominator of X, which is the parent of X
   in the dominator tree.
[Note that the first sentence is not very specific, since it leaves it
 open to the imagination of the reader if a path goes over its endpoint.
 But the second is explicit, stating that the relation is reflexive, i.e.
 every block dominates itself.]