C source documentation program (SUMMARY)

[Bob Ankeney]

Recently I posted the request:

&      I'm looking for a C source code documentation program.  Something that,
& for each function in a C program, lists the arguments passed, global variables
& referenced/modified, and functions called.  Can anyone point me to such a
& beast?  Something that would embed the information as comments would be
& extra-nifty!

     In summary, here are my responses:

     Several people pointed me to the latest Dr. Dobbs special C source edition
to the article 'Automatic Module Control Revisited'.  This program documents
C procedure call usage in both graphical representation and textual cross-
reference formats.  I uploaded the code from Compuserve and compiled it.
Looks nice, but has a few problems.  Also it doesn't deal with function
arguments and global variables.  It runs on Unix, MSDOS and VMS.


     Simon Leinen pointed out a neat emacs macro:

& Several weeks ago, `tegra.el' was posted to gnu.emacs (I think).  From
& the file header:
&
& 	;;;	tegra.el
& 	;;;
& 	;;;	This file contains Tegra-Varityper specific code documenting and
& 	;;;	formatting functions.
& 	;;;
& 	;;;	Written by Johnathan Vail, Tegra Inc.
& 	;;;
& ..
& 	;;   C-Ct   Insert timestamp like this: 22 Feb 1989 JV	-
& 	;;   C-Cd   Will insert at point a Tegra header with most fields filled
& 	;;   C-Cn   Insert at point a blank Tegra header
& 	;;   C-Cl   Insert at point functions used in following C function
& 	;;   C-Ch   Insert at point a Tegra source file (module) header, filled out
& 	;;   C-cu   Update file header.
&
& .. and this is a header generated for a random (in this case C++)
& function ...
&
& 	/*++***********************************************************************
& 	*
& 	* top_level_loop - 
& 	*
& 	* Revision History:
& 	*	29 Dec 1989 SL	- Created
& 	*
& 	* Synopsis:
& 	*	top_level_loop (FILE * source, TosDisk td)
& 	*
& 	* Description:
& 	*
& 	* Return Value:
& 	*
& 	* Parameters:
& 	*	FILE * source, TosDisk td
& 	*
& 	* Global Variables:
& 	*
& 	* Functions called:
& 	*	command_loop
& [sic!]	*	sizeof
& 	*
& 	* Side Effects:
& 	*
& 	* See Also:
& 	*
& 	* Technical Notes:
& 	*
& 	* Known Bugs:
& 	*
& 	* Example:
& 	*
& 	**--***********************************************************************/
& 	
& 	extern ReturnCode
& 	top_level_loop (FILE * source, TosDisk td)
& 	{
& 	  ...
& 	}
&
&
& -- 
& Simon Leinen
& simon at tubopal.UUCP
& simon%cs.tu-berlin.de at db0tui6.BITNET

     This is quite nice.  It has a few bugs (as does the previous utility) such
as not handling #ifdef's too well, but otherwise is very useful.


     Several people mentioned Polytron PolyDoc from Sage Software.
Unfortunately, this only runs under MSDOS.  For details you can call
1-800-547-4000.  It generates a documentation database.



     And finally, Ken Nelson at oresoft!uunet!jarthur!ssdken sent:

& Our tool CDADL (C Design and Documentation Language) is exactly 
& what you asked for.  It even includes embedding information in comments
& that can be extracted automatically for documentation.  You end up with
& readable, understandable source code, and get documentation for free.
&
& CDADL generates a lot of information on it's own.  Things like variable set
& use cross references, type, module, and macro cross references.  Also the
& code is pretty-printed (configurable of course).  I can send you more
& information, if you give me your address. Also let me know what kind
& of hardare you need it on.  It runs on most Unix machines, Dec/VMS machines
& and MS-DOS.
&
&
&				Ken Nelson
&				Software Systems Design
&				3267 Padua Av
&				Claremont, CA 91711
&				(714) 624-3402

     Their company has a lot of utilities for documenting source as well as
tracking projects.



     Thanks to all who responded!  I still haven't found quite what I'm
looking for.  At present I'm settling for the tegra macro plus some fill-in-
the-blank type editing, though CDADL looks like a strong possibility (cost
is $5000 and it may have more capabilities than I need).

     Any other pointers would be greatly appreciated.

		Bob Ankeney

----------------------------------------------------------------------
Bob Ankeney                    | "Yield and overcome.                |
...!tektronix!reed!bob         |  Bend and be straight.              |
...!tektronix!bob at reed.BITNET  |  Empty and be full."    - Lao Tzu   |
----------------------------------------------------------------------