RFC: Creating a live, all-encompassing architectural document for GCC

[Basile STARYNKEVITCH]

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} ***