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.
