Re: "Documentation by paper"

[kenner at vlsi1 dot ultra dot nyu dot edu (Richard Kenner)]

    Though sometimes it is difficult to find a more concise way to
    describe the algorithms than is found in the references.  

It's perfectly reasonable to paraphrase the description in the reference.
The reference itself, of course, will have lots more information than
the algorithm, so that description would only be a fraction of the size of 
the whole reference.

    What I tend to be particularly interested in is implementation
    details, flaws in the paper, limitations imposed due to our
    framework/implementation, differences in design decisions, etc.

Right, but that's hard to do without having a separate description of
the algorithm because the best way to do those things is inside the
narrative of the algorithm.

    One of the interesting questions I'm working through right now is to
    figure out how much I should assume the reader knows.  For example, do
    I assume that everyone knows what dominators and post-dominators are?
    What about a dominator tree?  Value numbering? SSA form?  How using
    value numbering on the SSA form during a dominator walk gives us
    redundancy elimination on an almost-global scale without the need to
    invalidate values from our hash tables?

I can't answer for people in general, but I don't know what *any* of those
things are and I would expect to see at least a definition of any of those
terms in adequate documentation.  Of course, the documentation can't
substitute for a good compiler text, but there should at least be a few
sentences saying what each thing is.

    Which brings me to the need for this kind of documentation to also
    live in the modern world of the web -- hyperlinks from the optimizer's
    high level documentation back to the underlying concepts it builds
    upon, IMHO, is much better than bringing up a zillion files in your
    favorite text editor.

In some ways, sure, but often the best way to study code is to do it
on a long plane flight and that means having everything in a couple of
well-defined places.