Groups | Search | Server Info | Login | Register

Groups > comp.lang.java.programmer > #5523

Re: The greeting code in Java

Show all headers | View raw

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

Back to comp.lang.java.programmer | Previous | Next — Previous in thread | Next in thread | Find similar

Thread

The greeting code in Java Saeed Amrollahi <amrollahi.saeed@gmail.com> - 2011-06-19 06:05 -0700
  Re: The greeting code in Java rossum <rossum48@coldmail.com> - 2011-06-19 17:36 +0100
    Re: The greeting code in Java Saeed Amrollahi <amrollahi.saeed@gmail.com> - 2011-06-19 12:15 -0700
      Re: The greeting code in Java Martin Gregorie <martin@address-in-sig.invalid> - 2011-06-19 19:46 +0000
        Re: The greeting code in Java Saeed Amrollahi <amrollahi.saeed@gmail.com> - 2011-06-19 22:34 -0700
          Re: The greeting code in Java Jukka Lahtinen <jtfjdehf@hotmail.com.invalid> - 2011-06-23 11:43 +0300
        Re: The greeting code in Java Martin Gregorie <martin@address-in-sig.invalid> - 2011-06-20 10:13 +0000
          Re: The greeting code in Java Michael Wojcik <mwojcik@newsguy.com> - 2011-06-22 09:29 -0400
      Re: The greeting code in Java Joshua Cranmer <Pidgeot18@verizon.invalid> - 2011-06-19 16:00 -0400
      Re: The greeting code in Java Eric Sosman <esosman@ieee-dot-org.invalid> - 2011-06-19 16:05 -0400
        Re: The greeting code in Java Saeed Amrollahi <amrollahi.saeed@gmail.com> - 2011-06-19 22:40 -0700
      Re: The greeting code in Java rossum <rossum48@coldmail.com> - 2011-06-19 22:28 +0100
  Re: The greeting code in Java Roedy Green <see_website@mindprod.com.invalid> - 2011-06-19 21:14 -0700
  Re: The greeting code in Java Roedy Green <see_website@mindprod.com.invalid> - 2011-06-19 21:23 -0700
  Re: The greeting code in Java blmblm@myrealbox.com <blmblm.myrealbox@gmail.com> - 2011-06-20 19:20 +0000
    Re: The greeting code in Java Ney André de Mello Zunino <zunino@softplan.com.br> - 2011-06-22 15:55 -0300

csiph-web