Re: "Documentation by paper"

[Daniel Berlin <dberlin at dberlin dot org>]

On Feb 10, 2004, at 12:46 PM, Kai Henningsen wrote:

> dberlin@dberlin.org (Daniel Berlin)  wrote on 09.02.04 in 
> <67F3F3F9-5B2D-11D8-ABD3-000A95DA505C@dberlin.org>:
>
> > On Feb 9, 2004, at 1:13 PM, Robert Dewar wrote:
> >
> > > Daniel Berlin wrote:
> > >
> > > > This is theoretical.
> > > > I provided some data that showed at least one algorithm that claimed
> > > > they wanted "useless" phi nodes to be present worked slightly better
> > > > without them.
> > >
> > > Well surely it is part of the specification of the *implementation*
> > > whether these "useless" nodes are supposed to be present or not.
> > No, and you've missed my point.
> > The paper on the exact algorithm we implement claims they help.
> > With an implementation implemented *EXACTLY* according to this
> > algorithm, they do not help.
> > That is all.
> > It has nothing to do with an implementation difference.
>
> I smell a case of not seeing the wood for the trees.
Whatever.
Someone mentioned something that wasn't related to the thread, which is 
that they thought they read in a paper that a certain algorithm 
required useless phi nodes.
I responded that I had provided evidence to contradict this.
It had nothing to do with documentation per se, actually, it was just 
dragged back into the documentation thread by someone saying the fact 
that there is no restriction where nobody would expect one,  should be 
documented, which is actually a bit silly.

> Or in other words, it's you who didn't get the point. This thread is 
> NOT
> about what a specific optimizer wants to see wrt.

>  PHI nodes, it is about
> DOCUMENTING things like what this optimizer wants to see,

The optimizer doesn't care what it sees here.
What is there to document?

>  whatever that happens to be.

Right.
"This optimizer accepts everything given to it, just the same, and 
optimizes it all equally well"
That's real useful.
Any optimizer than can't optimize certain things or patterns should 
certainly be noted what they can't optimize (if only so they can be 
improved), but that is *NOT* the case here.
Here the case is that there *IS* no restriction.  Thus, there is 
nothing to document in regards to a restriction.
Of course, i'm sure someone else will say that we should document the 
fact that there is no restriction, lest some alien from mars be reading 
the code and on that planet, they assume restrictions that we don't.

Of course, it's that style of documentation that reminds me so much of 
the statutes i end of reading for various classes, and causes my eyes 
and brain to bleed.   Congress tries to documents things in at least a 
thousand pages per spec. (I could also point out that even as detailed 
as they are, they never work anyway. Imagine that. Developer 
documentation [which is what it really is] that is both voluminous and 
highly detailed, and doesn't help at all)