Path: csiph.com!x330-a1.tempe.blueboxinc.net!usenet.pasdenom.info!news.dougwise.org!nntpfeed.proxad.net!proxad.net!feeder1-1.proxad.net!198.186.194.247.MISMATCH!news-out.readnews.com!transit3.readnews.com!postnews.google.com!news2.google.com!npeer02.iad.highwinds-media.com!news.highwinds-media.com!feed-me.highwinds-media.com!spln!extra.newsguy.com!newsp.newsguy.com!news1 From: Michael Wojcik Newsgroups: comp.lang.java.programmer Subject: Re: The greeting code in Java Date: Wed, 22 Jun 2011 09:29:38 -0400 Organization: Micro Focus Lines: 52 Message-ID: References: NNTP-Posting-Host: p7e1a00e45db8d35dbb6ced180a651d080f8a7326cc19af06.newsdawg.com Mime-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 7bit User-Agent: Mozilla/5.0 (Windows; U; Windows NT 6.0; en-US; rv:1.8.1.23) Gecko/20090812 Thunderbird/2.0.0.23 Mnenhy/0.7.5.0 In-Reply-To: Xref: x330-a1.tempe.blueboxinc.net comp.lang.java.programmer:5523 Martin Gregorie wrote: > > IMO the main advantage of Javadocs over virtually all the other program > documentation tools Where "virtually all" apparently means "except for all of the many other tools that do this". > is that it can generate documentation from a program > source that follows the conventions and requires a minimum of of > documentary annotation. The technique of annotating source code with documentation markup long antedates Java. Around 1970 Peter Conklin was doing that with MACRO-10 sources and RUNOFF.[1] This is an old, old idea; it has its origins in the design of COBOL, which was intended to be readable by non-programmers (specifically by accountants and legal staff, who could check for regulatory compliance), and so incorporated various commenting mechanisms, including "NOTE" paragraphs with arbitrary text embedded in the source. The idea of extracting documentation from the source, as opposed to keeping the source as part of the documentation, showed up about ten years later, toward the end of the 1960s. > Compare that with the requirement that C > documentation must be a separately maintained (n|g)roff text file This "requirement" is a fantasy. The C language does not specify any documentation mechanism. There are any number of approaches to combining documentation and source code for C, including javadoc-like systems such as Doxygen and far more ambitious Literate Programming systems such as cweb. > that > can be almost unreadable in raw form, though the latest versions of less > do remove a lot of the formatting and checking nausea. There's no reason why roff sources need to be "unreadable in raw form", except that they were written by careless authors. And, incidentally, groff is a relative latecomer; "classical" UNIX offered nroff and troff executables (typically two links to the same binary), and later ditroff. groff is just the GNU implementation of the roff family, with their usual random grab-bag of additional features. nroff and troff are of course descended from CTSS RUNOFF, via the PDP-7 roff (written in BCPL), then the first UNIX roff for the PDP-11, followed by nroff, then troff. [1] https://groups.google.com/group/alt.folklore.computers/browse_thread/thread/707c7faadd3b85dd/16871937ef091948