Hey,
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.
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
Received on Fri May 11 2012 - 19:34:00 CEST