An issue for the SC: horrible documentation quality of GCC

[Richard Kenner]

I want to repeat what I just said in a separate message: the amount of
totally undocumented code in GCC is approaching very troublesome levels.
There are who areas of the compler in which nobody but their author can
work due to a complete lack of any high-level documentation.

The local_cprop_* functions in gcse are a very good case in point.

There is no comment anywhere that I can find of the form "This phase performs
the ABC optimization by doing the following algorithm.  This optimization
is useful because XYZ and does not duplicate a similar optimization in QQQ
because of BAR."

>From the name, I can conclude this has *something* to do with "local
constant propagation".  If I studied the code long enough, I could probably
figure out what it actually *does*.

But there is no way to figure out the really important part of the
missing documentation, which is what the phase is *supposed* to do and
the motivations for the new phase.

This is by no means the first time this has happened: it most cases when I've
had to look at a relatively-recent part of the compiler, I find this lack
of documentation and I have complained about it before.

There's no point in trying to understand how we got to this appalling state
of affairs, but we do need to decide how to proceed from now.  My suggestion
is the following:

(1) Do not allow any further patches to the compiler that do not have proper
documentation.

(2) Remove any parts of the compiler for which documentation is not supplied
by the 3.4 release.

It is very clear that the approach of supplying documentation later
does not work.