This is the mail archive of the
gcc@gcc.gnu.org
mailing list for the GCC project.
Re: "Documentation by paper"
Michael Matz wrote:
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
dominators before). Adjusting any rules whatsoever (or enforcing existing
once) is not going to help a little bit with that fact. And still Kenner
states the obvious again and again instead of helping. Note that you do
a similar thing. _That_ is my point.
How can we help? As we point out in detail, we can't write
documentation successfully for undocumented code written
by others. The burden of documentation must lie with the
authors of the code, nothing else can work successfully.
Doing it after the fact is not ideal, but if it has to be
done after the fact OK. But the documentation must be done
by those who wrote the code, know what it is supposed to do,
know why they made the choices they did, know whey they did
not do certain things that may otherwise appear obvious
choices, know what invariants hold in the code etc.
An interesting analogy is in real engineering. Suppose you are
Israel, and you have a Mirage jet fighter, but you lack the
documentation (i.e. blue prints) and France suddently decides
not to provide any more spare parts. Can you reverse engineer
to do it yourself. Answer: almost impossible, you can look at
a ball bearing for example, and measure its size, but you can't
measure the tolerance, which is all important. You just have to
have the blue prints with these specifications.
> Thread closed now? Pretty please?
Feel free to use the amazing kill thread capability of your
mailer (I trust it has this :-) The subject line has been
quite clear, and although we have deviated from the original
point (that a mere reference to a paper does not constitute
acceptable documentation), the discussion has in fact stayed
quite consistently on track.