Re: Extending javadoc for C/C++

richardm@cogs.susx.ac.uk (Richard Matthias)
8 May 1997 21:48:25 -0400

          From comp.compilers

Related articles
Extending javadoc for C/C++ masticol@scr.siemens.com (1997-05-03)
Re: Extending javadoc for C/C++ kelley@Phys.Ocean.Dal.Ca (1997-05-08)
Re: Extending javadoc for C/C++ dwight@pentasoft.com (1997-05-08)
Re: Extending javadoc for C/C++ nr@adder.cs.virginia.edu (Norman Ramsey) (1997-05-08)
Re: Extending javadoc for C/C++ richardm@cogs.susx.ac.uk (1997-05-08)
Re: Extending javadoc for C/C++ objsoft@netcom.com (1997-05-08)
Re: Extending javadoc for C/C++ ercs50@tattoo.ed.ac.uk (1997-05-12)
Re: Extending javadoc for C/C++ amoroso@mclink.it (1997-05-12)
Re: Extending javadoc for C/C++ r.m.muench@ieee.org (1997-05-13)
| List of all articles for this month |

From: richardm@cogs.susx.ac.uk (Richard Matthias)
Newsgroups: comp.compilers
Date: 8 May 1997 21:48:25 -0400
Organization: University of Sussex
References: 97-05-010
Keywords: tools, documentation, Java

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.


: - The best competitor, Don Knuth's "literate programming" and CWEB
: (http://www-cs-faculty.Stanford.EDU/~knuth/books.html) have not taken
: off in widespread practice, for whatever reason.*


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




Richard
--


Post a followup to this message

Return to the comp.compilers page.
Search the comp.compilers archives again.