MIKE STEFFEN <[log in to unmask]> wrote in message
news:hb-dnZB7DKE7NHWiRVn-jw@fidnet.com...
> I have several programs which I've inherited that are not documented very
> thoroughly and I now have the need to modify.
> .....
> I'm wondering what those on the list who face this problem find to be the
> most effective documentation method(s) for existing programs.
>  ....

I would recommend that you take a look at Doxygen.  It will help with your C
code, but unfortunately not with the COBOL.

http://www.stack.nl/~dimitri/doxygen/

Doxygen will grovel through a bunch of source files and produce indexes and
cross references, "where used" concordences, inheritance diagrams (for C++).
It will also document your struct and typedefs.  But wait, there's more! :-)

Doxygen is really meant to be used as a system to help extract code and API
docs from your codebase--sort of like JavaDoc for Java.  To get the best
mileage out of it you really need to have special comments in your code, as
is the case with JavaDoc.  However, I have found that Doxygen does a
credible indexing job when run against a random codebase, thus my plug for
using it as an exploration tool. It can produce HTML output, or other
formats such as PDF, RTF, postscript, unixish runoff formats, etc.

From the Doxygen website:
=====================
"Doxygen is a documentation system for C++, C, Java, IDL (Corba and
Microsoft flavors) and to some extent PHP and C#.  It can help you in three
ways:
1) It can generate an on-line documentation browser (in HTML) and/or an
off-line reference manual (in ) from a set of documented source files. There
is also support for generating output in RTF (MS-Word), PostScript,
hyperlinked PDF, compressed HTML, and Unix man pages. The documentation is
extracted directly from the sources, which makes it much easier to keep the
documentation consistent with the source code.
2) You can configure doxygen to extract the code structure from undocumented
source files. This is very useful to quickly find your way in large source
distributions. You can also visualize the relations between the various
elements by means of include dependency graphs, inheritance diagrams, and
collaboration diagrams, which are all generated automatically.
3) You can even `abuse' doxygen for creating normal documentation (as I did
for this manual). ....."
========================

One other note: I have used just the Windows version of Doxygen, which works
very nicely with no fancy install needs.  YMMV if you need to use the unix
or Mac versions.

Have fun!
lcl

* To join/leave the list, search archives, change list settings, *
* etc., please visit http://raven.utc.edu/archives/hp3000-l.html *