"Documentation by paper"

[Steven Bosscher]

On Tuesday 03 February 2004 17:18, Richard Kenner wrote:
>     You can leave out an explanation of what a dominator is and still
>     be self-contained.
>
> Not in the sense that it has been in the past.
>
>     What's next, do we have to explain what a finite automaton is in the
>     sources of GCC?
>
> It's always hard to know where to draw the line, but it would seem to me
> that in any case where you have a finite automaton, the description of the
> automaton itself would almost serve as a definition-by-example of the term.
>
> As an example of the sort of thing I'd expect to see, look at the Bison
> manual.  Not only does it not simply leave "LALR(1)" to be looked up (and
> that's a much more well known term than those previously mentioned), it
> even defines "context-free grammar" and "symbol".

The difference here is that you are talking about a bison _user_ manual.  This
discussion was, AFAICT, about GCC internals documentation.  I honestly don't
believe that anyone working on compiler optimizations does now know/understand
the concept of dominance, or DFA, and so on. These are just computer science
fundamentals.  A user doesn't have to understand them, but any compiler writer
should.

I would like better internals/interfaces documentation too.  But I'd rather
focus on GCC specific implementation details than on terminology and basic
algorithms and concepts.

Gr.
Steven