Where to put code documentation?
- by Patrick
I am currently using two systems to write code documentation (am using C++):
Documentation about methods and class members are added next to the code, using the Doxygen format. On a server Doxygen is run on the sources so the output can be seen in a web browser
Overview pages (describing a set of classes, the structure of the application, example code, ...) is added to a Wiki
I personally think that this approach is easy because the documentation about members and classes is really close to the code, while the overview pages are really easy to edit in the Wiki (and it's also easy to add images, tables, ...). A web browser allows you to see both documentations.
My co-worker now suggests to put everything in Doxygen, because we can then create one big help file with everything in it (using either Microsoft's HTML WorkShop or Qt Assistant). My concern is that editing Doxygen-style documentation is much harder (compared to Wiki), especially when you want to add tables, images, ... (or is there a 'preview' tool for Doxygen that doesn't require you to generate the code before you can see the result?)
What do big open-source (or closed source) projects use to write their code documentation? Do they also split this up between Doxygen-style and a Wiki? Or do they use another system?
What is the most appropriate way to expose the documentation? Via a Web server/browser, or via a big (several 100MB) help file?
Which approach do you take when writing code documentation?
