Re: `javadoc` for c++

John Carter <john@dwaf-hri.pwv.gov.za>
22 Oct 1998 01:56:17 -0400

          From comp.compilers
Related articles
[3 earlier articles]
Re: `javadoc` for c++ qjackson@wave.home.com (Quinn Tyler Jackson) (1998-10-17)
Re: `javadoc` for c++ dwight@pentasoft.com (1998-10-17)
Re: `javadoc` for c++ Marko.Makela@HUT.FI (Marko =?ISO-8859-1?Q?M=E4kel=E4?=) (1998-10-17)
Re: `javadoc` for c++ objsoft@netcom.com (1998-10-17)
Re: `javadoc` for c++ comments@cygnus-software.com (Bruce Dawson) (1998-10-17)
Re: `javadoc` for c++ leichter@smarts.com (Jerry Leichter) (1998-10-17)
Re: `javadoc` for c++ john@dwaf-hri.pwv.gov.za (John Carter) (1998-10-22)
Re: `javadoc` for c++ matt@timmermans.no-spam-remove.org (Matt Timmermans) (1998-10-30)
| List of all articles for this month |
From: John Carter <john@dwaf-hri.pwv.gov.za>
Newsgroups: comp.compilers
Date: 22 Oct 1998 01:56:17 -0400
Organization: Compilers Central
References: 98-10-079
Keywords: C, documentation

On Tue, 13 Oct 1998, Marcus Rohrmoser wrote:


> Is there a tool that generates class-documentation from a c++ header
> like javadoc does from java-source?
>
> [C++ is nearly impossible to parse with yacc because it's so ambiguous
> see the archives for plenty of discussion. -John]


I was considering just this problem when it struck me as more
reasonable to generate the headers from the documentation. This is
basically Knuth's Literate programming idea taken one step further.


The idea is this...


Mix the C++ function declarations, documentation and implementation in
one file. Mark it up in XML. (See www.w3.org of info on XML)


Run it through James Clark's nsgmls to validate and parse the
XML. Feed that output into a wee perl scriptie from which flows a whole
bunch of streams.
1) The class interface (.h file)
2) The class implementation (.cc file)
3) The online documentation. (.html file)
4) The dead tree documentation (.tex file)


Now add to this the idea that C++ templates are @#$@! obscure. The
programmer using the templated class is left wandering just how did
the compiler implement that particular combination of instantiation /
traits / overloading / inheritance (ordinary/virtual) & polymorphism.


So add to the wee perl scriptie the ability to instantiate
templates. Leaving you with clean clear template free C++ code, with
each instantiation custom crafted and custom documented.


I have got as far as the wee perl scriptie to instantiate the
templates for me and was contemplating how to add the documentation.
It became obvious I was going to be "marking up" and hence I should
really be using XML.


Oh yes, and this adds yet another output stream. The "template"
documentation. The patterns and traits used by the template must also be
marked up and documented.


John Carter EMail: ece@dwaf-hri.pwv.gov.za
Telephone : 27-12-808-0374x194 Fax:- 27-12-808-0338
<http://www.geocities.com/SoHo/Cafe/5947> or <http://iwqs.pwv.gov.za>

Post a followup to this message

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