Re: Generating API documentation?

[Geoff Lane <geoff -at- GJCTECH -dot- FORCE9 -dot- NET>]

Geoff Hart wrote:
>> [snip]
The only utility I'm aware of that can produce API documentation is
the original developer. <g> I'm not sure what you're after here, but
based on what you've described, it seems like you want to be able to
create a list of the API calls in the code combined with the embedded
comments that describe them. If that's the case, it seems to me that
the simplest way to do this is to open the file in any word
processor, and scroll down through the file, deleting any irrelevant
text. But the embedded comments I've seen are usually cryptic and
inadequate for generating documentation. Unless your company has
fairly rigorous guidelines for documenting code, you may still have a
lot of work to do.

This isn't what I'd ordinarily consider to be API documentation,
though; that's usually a list of all the calls, their parameters, and
any usage notes, and you can't generate that automatically from raw
code because these aspects are all things that appear "under the
hood". Can you explain your problem more precisely?
<<
---
Hi Geoff,

Thanks for your input.

I accept that I need to flesh out any machine-produced documentation.  That
is, I need to at least write usage and purpose notes.  However, it would be
nice to have a piece of software do the worst of the 'handle-grinding'.

FWIW, the developers do a pretty good job of commenting their code.
Unfortunately, they don't stick to a rigid format.  Therefore, I'm looking
for something that will produce 'skeleton' topics.  That is, produce one
topic for each of the functions, variables, and constants that the API
exposes.  It would be nice if each topic contained a suitable table into
which I could place the 'human touch'.

I could develop a Word or WordPerfect macro to do this for me.  If I took
the trouble to write such a macro, then I'd also store the notes in a
database.  This would allow the same macro to re-document a revised API with
minimal effort on my part.  As a rough estimate, it would take me just over
a week to write the macro -- time for which I have better use.

OTOH, writing that macro could save a *lot* of future effort.  I just want
to be reasonably sure that I'm not re-inventing the wheel before proceeding.

Geoff Lane
Cornwall, UK
geoff -at- gjctech -dot- force9 -dot- net


 From ??? -at- ??? Sun Jan 00 00:00:00 0000=