Doxygen, written by Dimitri van Heesch, is one of the most useful packages for documenting software source code. See the Doxygen website for more info. First released in 1997, it is regularly updated. A huge amount of effort went into the package; it is extremely unlikely that a casual user will stumble across a better solution, or to even consider manually documenting source code.
We have been using Doxygen since 2000 and recommend using it even if you do no wish to modify your code, as the output allows indexed source navigation and viewing call graphs.
Manual methods based on pirated Windows products were common for project management in our bouts with corporates as an employee or contractor. There was little desire to consider an automated tool, let alone a useful free one. Even avionics code never seemed to be cross referenced or linked back to any of the requirements documents.
A few years back, I was one of about thirty people added onto a multi-million dollar project trying to document/ track PLC code manually for a tick-box sign-off — if you have ever been there you will know how far in the past automation vendors trawl expensive software. The manuals could have used some commercial documentation tools like the Adobe Suite, which would have been a drop in the ocean, or something equivalent to doxygen. I'll bet ten donuts that the documentation looks different to the installed base and that it will never be updated or cross-referenced.
There are plenty of examples of Doxygen documentation in open source projects. The interface files can be modified to suite the other CSS layout on a site, as was done in the SketchUp SDK Contents documentation. (Follow some of the links in the Contents, as the “Main Page” is not very different to the other pages, but the “Data Structures” and “Files” are impressive.)
Apple’s Xcode uses Doxygen to generate documentation. Apple adopted the package a few years ago. The better supported evaluation boards from Atmel and others have been supporting Doxygen for years. As its popularity increased, it was ported to more platforms and supported more languages, even hardware description languages.
Shortly after arriving in Australia, I contracted on a weekly basis. The projects were fairly small to fill in — one small enough to complete in two or three weeks was pushed through the usual LaTeX and Doxygen run. The LaTeX manual is encoder.pdf (1,3Mbytes), and the Doxygen output is refman.pdf (684 kBytes).
The HTML output from Doxygen is a bit big to post (large number of directories and files), but for supplying searchable output, is the preferred route. All that is required is selecting Yes for the configuration on the Mac (or editing the doxyfile on a Linux platform where the HTML output line is).
Mutterings about us using Adobe tools for documenting software source code is unlikely to happen, as we failed to sort out acronyms and cross referencing in InDesign, plus we can tweek Doxygen and pull in other TeX files.
So how important is Doxygen? Dot and Graphviz integration are standard, which create graphics of call graphs without even having to change any source code. Having documentation in simple text for output through pdfLaTeX will give some longevity to your legacy projects (present stuff plus six months or older).
If you have to update or rewrite a major collection of code in a programming language supported by Doxygen, we could edit the source files and tweek the TeX support files, or the CSS files. The tweeking or updating are pretty much “a one-off” as the package is updated fairly frequently. The final output should not require any manual intervention or tweeking, otherwise programmers will not use it. It is also not a job description that anyone would like for more than a month. Once installed and part of the development cycle, no further contracting is necessary.
© 2014 — Second Valley Software Pty Ltd. All Rights Reserved