Re: [dev] suckless document generator for C code

From: Amit Uttamchandani <amit.uttamchandani_AT_my.csun.edu>
Date: Fri, 11 May 2012 11:06:05 -0700

On Fri, May 11, 2012 at 06:34:00PM +0100, Connor Lane Smith wrote:
> On 11 May 2012 17:45, Amit Uttamchandani <amit.uttamchandani_AT_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!
Received on Fri May 11 2012 - 20:06:05 CEST