Diego Novillo wrote:
This idea is still very raw in my mind, so apologies in advance for
being deliberately vague. For the last few weeks I have been thinking
on ways to address the sorry state of our internal documentation.
We all agree that none of us has global knowledge of all aspects of
the compiler. It's just impossible. So, we have the collective
knowledge distributed all over the place but it is pretty hard for
someone to navigate the compiler without talking to N different
people.
So, I think the problem goes a bit beyond mere documentation of how a
module works at a high level. I would like to have a navigable
document that also describes the flow of things, interfaces and
helpers. Starting at main.c:main() and ending at toplev.c:finalize().
Maybe a possible approach would be to use literate programming
techniques; By previous experience (still limited), I would believe that
it would be more worthwhile on the interface files (ie the *.h files,
some *.opt, etc...) than on the implementation files (*.c)
Still, it is a lot of work, and it would mean to change the coding
guidelines & coding rules expected by GCC contributors.
I am more thinking loud than actually believing that it would be a good
idea to switch to literate programming; I have mixed feelings towards
this approach, which has been extensively used in the C-- compiler
http://cminusminus.org/ . My personal (biased) view is that
sophisticated compiler technology should be coded in higher level
languages than C, C++ or Java
Maybe a better discipline would be to expect every coder to document his
stuff on the GCC wiki.
All this is more a social issue than anything else. We developers don't
like documenting our work (and this is sadly true for me too!)
(Diego, I am busy preparing the basilys branch, see my GCC summit paper).
--
Basile STARYNKEVITCH http://starynkevitch.net/Basile/
email: basile<at>starynkevitch<dot>net mobile: +33 6 8501 2359
8, rue de la Faiencerie, 92340 Bourg La Reine, France
*** opinions {are only mines, sont seulement les miennes} ***
