Path: csiph.com!x330-a1.tempe.blueboxinc.net!usenet.pasdenom.info!gegeweb.org!de-l.enfer-du-nord.net!feeder1.enfer-du-nord.net!feeds.phibee-telecom.net!usenet.ukfsn.org!not-for-mail From: Martin Gregorie Newsgroups: comp.lang.java.programmer Subject: Re: The greeting code in Java Date: Mon, 20 Jun 2011 10:13:04 +0000 (UTC) Organization: UK Free Software Network Lines: 42 Message-ID: References: NNTP-Posting-Host: 84.45.235.129 Mime-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-Trace: localhost.localdomain 1308564784 8484 84.45.235.129 (20 Jun 2011 10:13:04 GMT) X-Complaints-To: usenet@localhost.localdomain NNTP-Posting-Date: Mon, 20 Jun 2011 10:13:04 +0000 (UTC) User-Agent: Pan/0.133 (House of Butterflies) Xref: x330-a1.tempe.blueboxinc.net comp.lang.java.programmer:5421 On Sun, 19 Jun 2011 20:24:13 +0000, Stefan Ram wrote: > Martin Gregorie writes: >>C/C++ doesn't have a standard documentation tool that comes near >>Javadocs. > > Classical C was part of UNIX, and its »standard documentation tool« > was »(n|g)roff -man«/»man«. > Indeed - and this is not exactly or portable (as you said) and rarely found outside the *NIX world. IMO the main advantage of Javadocs over virtually all the other program documentation tools is that it can generate documentation from a program source that follows the conventions and requires a minimum of of documentary annotation. Compare that with the requirement that C documentation must be a separately maintained (n|g)roff text file that can be almost unreadable in raw form, though the latest versions of less do remove a lot of the formatting and checking nausea. However, less, like (g|n)roff is also almost unknown outside the *NIX world. > However, it has not been man portable together with C > Indeed - text editors are everywhere but the same can't be said about (n|g)roff. I ended up writing my own Javadocs knock-off for C (cdoc) that can generate HTML that approximates a cross between Javadocs indexing/ pagination and the usual C library documentation format. It can do a reasonable job of documenting unmodified C source provided only that it has a heading comment for the C source file and a preceding comment for each function. Its also highly portable, since I wrote it in Java. -- martin@ | Martin Gregorie gregorie. | Essex, UK org |