On Sun, Sep 7, 2008 at 15:27, Basile STARYNKEVITCH <[EMAIL PROTECTED]> wrote:
> Given that passes are central to the middle end in GCC, shouldn't we want > each of them (without exception!) be described by at least a simple > paragraph. I'm sure that is a small effort for each pass writer (he/she > knows what he has coded) but it is a huge effort for somebody not > understanding them. Should we aim for some structured comments, for some > requirements regarding documenting the pass in the doc/*texi files, in the > wiki, ...? Yes, absolutely. The problem, as usual, is lack of time. Our standards for internal documentation are pretty bad and the set of people writing the documentation is always different than the set of people using the documentation. Sometimes the problem is not so much the lack of documentation, but its organization. Chunks of it live in header files, other chunks in C files, some (generally stale) documentation lives in doc/*.texi or individual wiki pages. Then there are the various articles and presentations given by various maintainers. Organizing and maintaining that documentation is a big job and it can be quite a demanding job. When preparing some of the internal presentation I linked to the wiki, I remember spending several days organizing material. It also needs constant attention, it's not just a matter of spending N days once. OTOH, whoever is interested in this project does not necessarily need to be an expert maintainer. The existing documentation plus a debugger and a bit of patience is enough. In fact, I strongly believe that a maintainer is *not* the right person to do this, as it is very easy for them to overlook things. I realize this is not helpful to your immediate problem. We all agree that the state of internal documentation in GCC is in a sorry state, but to solve the problem you need to address two issues: (1) Initial generation and (2) maintenance. In terms of the initial documentation, you will have a hard time pushing anything other than .texi. In general, people will oppose automatic generation of documentation a-la doxygen (I've tried several times), and formats other than .texi are also strongly discouraged (http://gcc.gnu.org/ml/gcc/2008-06/msg00301.html). As far as maintenance goes, once we have the initial set created. We should treat internal documentation the same way we treat documentation for newly added switches. We have historically been pretty lax about this, and that has caused the present situation. Diego.
