Steve Masticola (masticol@scr.siemens.com) wrote:: I've been looking into embedded documentation mechanisms for C/C++,: and have come to a couple of conclusions:: - javadoc is the most widely-accepted mechanism for embedded: documentation in C-like languages.

In Java-like languages surely. I've not heard of anyone using it with
any other language.

I don't think tools like javadoc compete with literate
programming. Literate programming is a whole ideology and it is very
difficult to "retrofit" documentation to a program (or even a small
part of a program) in this way. Javadoc and similar tools don't push
anywhere near so hard.

: In any case, is anyone working on extending javadoc to C/C++, and/or: building an extractor that doesn't rely on the Java sandbox? It's not: quite sufficient for languages where not everything is a class.

There are a number of tools that preceded javadoc. Nothing else in
Java is particularly original (OK, that was blatant flame bait - Don't
follow up :-), so why should you expect javadoc to be? I've seen at
least two such tools for C freely available and there ought to be
similar tools available for c++ probably commercially (I know Hitachi
sell the mother of all reverse engineering packages although the name
doesn't spring to mind right now). The only one I could find in a
hurry is this, from the Linux archives (although it should run on any
UNIX):-

Title: Cxref - C program cross-referencing & documentation tool
Version: 1.3 [Dec-08-96]
Entered-date: 08DEC96
Description: A program that takes as input a series of C source files
and produces a LaTeX or HTML document containing a cross
reference of the files/functions/variables in the program,
including documentation taken from suitably formatted
source code comments.
The documentation is stored in the C source file in
specially formatted comments, making it simple to maintain.
The cross referencing includes lists of functions called,
callers of each function, usage of global variables, header
file inclusion, macro definitions and type definitions.
Works for ANSI C, including many gcc extensions.
Keywords: C programming document cross-reference
Author: amb@gedanken.demon.co.uk
Maintained-by: amb@gedanken.demon.co.uk
Primary-site: ftp.demon.co.uk /pub/unix/unix/tools
225k cxref-1.3.tgz
Alternate-site: sunsite.unc.edu /pub/Linux/devel/lang/c