Re: Extending javadoc for C/C++

ercs50@tattoo.ed.ac.uk (robby)
12 May 1997 00:16:47 -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: ercs50@tattoo.ed.ac.uk (robby)
Newsgroups: comp.compilers
Date: 12 May 1997 00:16:47 -0400
Organization: Edinburgh University
References: 97-05-085
Keywords: documentation, C, tools

Dan Kelley (kelley@Phys.Ocean.Dal.Ca) wrote:
> Steve Masticola (masticol@scr.siemens.com) wrote:
> : - 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 agree with the reason given. Knuth's is too complicated.
> Unfortunately, I am EXACTLY in the category for which Knuth's scheme
> is best suited: I'm a scientist who often needs to describe code by
> complex formulae (e.g. differential equations with lots of partial
> derivatives, etc), and for these the mathematical typesetting of TeX
> is ideal. However, nobody in my research group has chosen to use
> literate programming -- it just seems too difficult in practice. In
> fact I've never seen scientific code with 'literate' comments.


No, literate programming tools are actually very simple. Take a look
at noweb or nuweb. The technical issues involved are extremely simple,
it is the philosophy behind LP that is sort of complicated. I believe
that most programmers are so deeply involved with writing programs for
the machines to understand, that they do not understand the need for
fellow humans to understand their code as well. LP tools give you the
means to write a program as if you were explaining it to someone and
then translate it mechanically into one the compiler/interpreter will
grok. The biggest stumbling block is usually the typesetting program
that is used; almost all LP tools use TeX, but most also allow you to
write your text for other environments, like html.


The tools are simple, the idea is simple, most programmers have just
never learnt or have forgotten how to write down explanations for
their code. I have still to meet someone who actually used LP and
then said it was not worthwhile.


Here's a pointer to noweb : http://www.cs.virginia.edu/~nr/noweb/intro.html


Robby


--
Robert Raschke robby@epc.co.uk
--


Post a followup to this message

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