bob@reed.UUCP (Bob Ankeney) (01/10/90)
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@tubopal.UUCP
& simon%cs.tu-berlin.de@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@reed.BITNET | Empty and be full." - Lao Tzu |
----------------------------------------------------------------------