[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: IDL Documentation tool?

Daniel Luebbert wrote:
> Hi there,
> I am trying to generate a documentation for a large bunch of IDL
> programs of mine,
> so that someone else could easily understand and use them.
> Does anyone know of a program, PERL script, commercial tool or whatever
> else
> which could generate a complete documentation from the source code?

No. That's fundamentally an impossible task. Complete documentation
includes things that don't reside in your source code and can't be
derived from it, such as a list of the requirements it must meet, a
description of how it fits into the larger picture, explanations of your
design decisions (including why you DIDN'T do certain things), a user's
guide, and the revision history.
Now, in any language that supports comments, you can insert those things
in your code, but they can't be derived from the code itself.

> It should certainly include a list of routines in each file, with the
> respective arguments and keywords,
> and also extra any header documentation like "doc_library" does.
> But ideally it should also analyze which other routines each file uses,
> maybe detect common block incompatibilities,
> etc., etc...

Those are all useful things to do; just don't confuse them with
"complete" documentation.
Unfortunately, I'm unaware of any existing facilities for collecting
such information from IDL files, but others may know more about such