Hey, On 11 May 2012 17:45, Amit Uttamchandani <amit.uttamchand...@my.csun.edu> wrote: > I'm looking for a document generator for C code. Mainly to document APIs > to give to UI developers.
I'm of the belief that documentation generators vary between useless and harmful. When you embed documentation into the program source itself, you're choosing either to have very concise documentation, or to have totally unwieldy comments. In the case of generators like Javadoc you even include HTML in the comments, which means no one can actually read them. Most people fall back on stupid text editing features like code folding, so they don't have to see all this commented nonsense, and then nobody updates the documentation anyway, which means the entire thing is useless. In my opinion you have two sane options: either you can keep the documentation and source apart, and rely on yourself to keep the two in sync; or you can stick the information for each function in the C header file, which then acts as plaintext documentation without all the hassle of generating HTML. "The best way to solve any problem is to remove its cause." Connor
