Re: "Documentation by paper"

[Robert Dewar <dewar at gnat dot com>]

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.
Actually you want to know if the producer is supposed to produce
them, and whether the consumer requires/prohibits/tolerates them.

Remember this thread is about documentation. This kind of detail
is exactly the sort of thing that the documentation should provide.

It's also a very good indication of why you can't easily reverse
documentation from engineering.

Suppose the spec is

Producer is not supposed to produce "useless" nodes.

Consumer is supposed to tolerate them if they are produced

Now in practice the consumer does not get tested with useless
nodes, but it is supposed to accept them. It may be quite
difficult to tell that this is the case from just the code.
Furthermode, if there is a latent bug where one of these
nodes would blow up the consumer, then the reverse engineered
documentation might incorrectly conclude that the consumer
is not supposed to tolerate them.

It's really not that much trouble to pin things like this
down with proper documentation!