On Fri, May 11, 2012 at 06:34:00PM +0100, Connor Lane Smith wrote: > 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. >
Makes sense... > 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. > I guess I like the idea of keeping all the information in the C header file. This makes it clean. The problem right now is the APIs are kept in a MS Word Office 2010 .docx file, which doesn't work right with LibreOffice. So I would prefer anything else over using MS Word to update the API docs. Thanks for your reply!
