 |
| Prev-20 | Home | Next-20 |
| Prev-20 | Home | Next-20 |
| Prev- | Prev- | Gcc | Oct- | Next- | Next- |
| Subject: | RFC: Creating a live, all-encompassing architectural document for GCC |
| Group: | Gcc |
| From: | Diego Novillo |
| Date: | 26 Oct 2007 |
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().
The key properties that I'm after are:
- Navigable.
From high-level details to low-level implementation of a single file.
This would be a set of browseable hierarchies that offer different
views of the documentation. For instance, one view would be a
decomposition of modules, each of which would offer a view of
submodules and such.
Another view could focus on the compilation flow.
- Live and easy to modify.
It should be easy for an individual maintainer (or even user) to go in
and modify parts of the document that are incomplete/missing/wrong.
This and navigability suggest a wikipedia-like approach. We even have
the beginnings of some of this in the wiki, so I would like to build
on that.
- Close correspondence to mainline.
This is where it gets hard. We need to have a way of enforcing code
updates that change internal or external API properties to be
reflected in the document. With this I don't mean that every single
patch should be accompanied with a documentation change. However, if
a patch refactors a module and its internal interfaces are changed,
then the patch should be accompanied with a change to the
documentation.
- Transfer from document to code
The documentation for individual modules and files should be linked to
the actual source code. Perhaps this could be automatically generated
with tools like javadoc or doxygen.
The high-level description of algorithms, strategies, heuristics,
interfaces, usage, etc live on the document and we provide links to
the automatically generated documentation or SVN live sources. This
would provide more low-level documentation in the form of individual
function documents and the usual things we request in each file.
So, I think my inclination is to provide this document as a wiki. The
current wiki should provide all the support we need. We can create
different views and organization incrementally, it's easy for people
to edit it, and we could put guards around if it started being abused.
My ultimate goal is to facilitate the transfer of knowledge. When
someone new wants to start working on GCC, we should be able to point
them to this document and say "here, drink from this hose".
Thanks.
| Prev- | Prev- | Gcc | Oct- | Next- | Next- |