This is the mail archive of the gcc@gcc.gnu.org mailing list for the GCC project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

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


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


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]