javadoc => adadoc?

javadoc => adadoc?

[nelson]

Are there any tools, public or otherwise, which can document an Ada
program like Sun's javadoc?  I perused the usual Ada web sites, but
didn't see anything (but there are a couple Ada html related tools).


Ken


-----== Posted via Deja News, The Leader in Internet Discussion ==-----
http://www.dejanews.com/rg_mkgrp.xp   Create Your Own Free Member Forum

Re: javadoc => adadoc?

[nabbasi]

In article <6ptlbe$k3$1@nnrp1.dejanews.com>, nelson@blaze-net.com says...

>Are there any tools, public or otherwise, which can document an Ada
>program like Sun's javadoc?  I perused the usual Ada web sites, but
>didn't see anything (but there are a couple Ada html related tools).
>
 
there was some discussion on this on some ada mailing lists.

it seems to me that the need for adadoc is much less than for java.

in java, there is no separation between the specification and implementation
of the package, so one uses the tool javadoc to 'pull out' the specifications
into an html nicly formatted output so one can look it and know what the API
is.

in Ada, one can simply look at the speification part of the package, no tool
is needed to 'pull out' the API out of the body as is the case with java.

one more reason why I think Ada is a better language than Java.

Nasser

Re: javadoc => adadoc?

[Norman H. Cohen]

nabbasi@earthlink.net wrote in message <6pvslq$poo@drn.newsguy.com>...

>it seems to me that the need for adadoc is much less than for java.
>
>in java, there is no separation between the specification and
implementation
>of the package, so one uses the tool javadoc to 'pull out' the
specifications
>into an html nicly formatted output so one can look it and know what the
API
>is.
>
>in Ada, one can simply look at the speification part of the package, no
tool
>is needed to 'pull out' the API out of the body as is the case with java.


While Java does not REQUIRE the separation between specification and
implementation, it certainly ALLOWS it:  A Java programmer can define an
interface and a class implementing that interface, achieving roughly the
same effect as writing a package spec and package body in Ada, and this is a
common Java practice.  (Unlike Ada, Java does not enforce hiding of the
implementation:   Another part of the program can access the implementation
by casting from the interface type to the implementation type.)  Thus
javadoc was not invented to make up for a supposed inability to separate
implementation and interface.

The true benefit of javadoc is the automated generation of hypertext
documentation that can be viewed with a browser.  Indices by package, by
class, and by method name, as well as links to related pages (e.g. from the
declaration of a parameter of type FileFilter in the listFiles method of
class File to the documentation for the FileFilter interface) are generated
automatically.  Tree diagrams showing the ancestors of a class are generated
automatically.  In JDK 1.2, javadoc also generates lists of descendents, and
lists methods that a class inherits from each of its ancestors.

This isn't rocket science, but it's damned convenient in large software
projects.  Any language, particularly an OO language, can benefit from this
kind of tool.

-- Norman Cohen

Re: javadoc => adadoc?

[Charles Hixson]

Norman H. Cohen wrote:
> 
> nabbasi@earthlink.net wrote in message <6pvslq$poo@drn.newsguy.com>...
	/* snip */ 
> The true benefit of javadoc is the automated generation of hypertext
> documentation that can be viewed with a browser.  Indices by package, by
> class, and by method name, as well as links to related pages (e.g. from the
	/* snip */ 
> -- Norman Cohen
And the main disadvantage of javadoc is that once a person gets a html
document, one is apt to be satisfied with that as having done the job of
documentation.  Unfortunately, this doesn't work so well except in a few
restricted contexts.  There is no global index, for example...just TRY
to turn javaDoc documentation into something that is useful off-line (it
can be done, but it isn't easy, at least not with the tools that I have
available!).
-- 
Charles Hixson	charleshixson@earthling.net
(510) 464-7733	or chixso@mtc.dst.ca.us

Re: javadoc => adadoc?

[Robert Dewar]

Norm said

<<> The true benefit of javadoc is the automated generation of hypertext
> documentation that can be viewed with a browser.  Indices by package, by
> class, and by method name, as well as links to related pages (e.g. from the
>>

Very nice, but not for a moment would I describe this as documentation!
The danger of such tools is precisely that it leads sloppy coders to
think that they don't need to document their code, because some automatic
tool can do it for them. Documentation is all about providing information
that is NOT readily derivable from the code, by either a human or by a
simple minded tool. For example, one critical aspect of documentation is
to say what you did NOT do and why you did NOT do it!

Re: javadoc => adadoc?

[Larry Kilgallen]

In article <dewar.902212445@merv>, dewar@merv.cs.nyu.edu (Robert Dewar) writes:
> Norm said
> 
> <<> The true benefit of javadoc is the automated generation of hypertext
>> documentation that can be viewed with a browser.  Indices by package, by
>> class, and by method name, as well as links to related pages (e.g. from the
>>>
> 
> Very nice, but not for a moment would I describe this as documentation!
> The danger of such tools is precisely that it leads sloppy coders to
> think that they don't need to document their code, because some automatic
> tool can do it for them. Documentation is all about providing information
> that is NOT readily derivable from the code, by either a human or by a
> simple minded tool. For example, one critical aspect of documentation is
> to say what you did NOT do and why you did NOT do it!

I have long felt that such human generated commentary has the best chance
in most shops of being:

	a) maintained

	b) read

during subsequent revisions if it is stored as comments in the source code
itself.  Sentinel characters to denote such special comments may be in order,
but it hardly need be so complex as HTML to convey meaning.  Extracting to
an external format can go through some arbitrary formatting process.

Larry Kilgallen

Re: javadoc => adadoc?

[Norman H. Cohen]

Larry Kilgallen wrote in message <1998Aug4.073510.1@eisner>...

>In article <dewar.902212445@merv>, dewar@merv.cs.nyu.edu (Robert Dewar)
writes:
>> Norm said
>>
>> <<> The true benefit of javadoc is the automated generation of hypertext
>>> documentation that can be viewed with a browser.  Indices by package, by
>>> class, and by method name, as well as links to related pages (e.g. from
the
>>>>
>>
>> Very nice, but not for a moment would I describe this as documentation!
>> The danger of such tools is precisely that it leads sloppy coders to
>> think that they don't need to document their code, because some automatic
>> tool can do it for them. Documentation is all about providing information
>> that is NOT readily derivable from the code, by either a human or by a
>> simple minded tool.

Of course any decent javadoc documentation includes extensive commentary
written by a human.  The principal job of  javadoc is to reformat annotated
comments about a class, interface, variable, or method into HTML.  The
automatically generated hyperlinks are useful to the extent that they link
you to informative commentary.

Sure, it is possible, and probably even useful, to run javadoc on
commentless files, just to get automatically generated indexes and hypertext
describing class hierarchies, method profiles, and so forth.  However, I
certainly agree that this does not constitute "documentation" of the code.

I don't know how common it is to use javadoc on source code that contains no
javadoc annotations.  I haven't run across such javadoc output myself.  I
heavily comment my own code regardless of whether I expect to run a
documentation-extraction tool on it.  When I code in Java, I adhere to
javadoc conventions for comments describing the overall purpose of a class
or interface and the meanings of a method's parameters, results, and
exceptions, for several reasons.  First, the notation is not TOO unnatural.
:-)  Second, it is a format easily recognized and understood by habitual
readers of Java source code.  Third, it leaves open the possibility that I
will actually feed the source file to javadoc some day.

>>                                     For example, one critical aspect of
documentation is
>> to say what you did NOT do and why you did NOT do it!

Yes, but that is design documentation, and javadoc is intended primarily to
produce documentation for the user of a software component.  Documentation
of a component's design is of interest to someone who is reading the source
code, so it makes sense to place design documentation in ordinary comments
in the source code.  In contrast, javadoc output is targeted to programmers
using the documented classes as black boxes.

>
>I have long felt that such human generated commentary has the best chance
>in most shops of being:
>
> a) maintained
>
> b) read
>
>during subsequent revisions if it is stored as comments in the source code
>itself.  Sentinel characters to denote such special comments may be in
order,
>but it hardly need be so complex as HTML to convey meaning.  Extracting to
>an external format can go through some arbitrary formatting process.

That's precisely what javadoc does.  It reformats specially annotated
comments written by humans.  In JDK 1.1, it reformats this information in
the form of HTML (which is far more difficult to read than the original
annotations if read directly, but extremely convenient to view through a
browser).  In JDK 1.2, there is a package com.sun.javadoc that reads javadoc
annotations and provides an ASIS-like interface for querying the information
that javadoc gathers.  You can write a program that Sun calls a "doclet"
 :-( ) to use the information provided by this interface, and JDK 1.2
includes a default doclet that generates HTML.

Here is an example to help clear up misconceptions about what javadoc does.
The class java.io.FileInputStream has a method named read, declared as
follows:

    /**
     * Reads up to <code>len</code> bytes of data from this input stream
     * into an array of bytes. This method blocks until some input is
     * available.
     *
     * @param      b     the buffer into which the data is read.
     * @param      off   the start offset of the data.
     * @param      len   the maximum number of bytes read.
     * @return     the total number of bytes read into the buffer, or
     *             <code>-1</code> if there is no more data because the end
of
     *             the file has been reached.
     * @exception  IOException  if an I/O error occurs.
     * @since      JDK1.0
     */
    public int read(byte b[], int off, int len) throws IOException {
        return readBytes(b, off, len);
    }

Anything surrounded by /* and */ is a comment in Java, but comments
beginning /** are extracted by javadoc.  Within such a comment, the '@'
character marks an annotation keyword.  The generated HTML can be found at
the following URL:

http://www.javasoft.com/products/jdk/1.1/docs/api/java.io.FileInputStream.ht
ml


Note the indexes to constructors and methods near the top of the page,
containing a one-sentence description of each method and a link to the
complete description.  (The first sentence of the complete description is
always used for the index.)  Click on the third overloaded read method in
the method index and the browser will bing you to the documentation
generated from the annotated source code above.  Click on any of the
hyperlinks to see other examples of javadoc output.

To summarize, javadoc is a handy tool which can provide effective
component-user documentation when used in a conscientiously applied program
of thorough commentary.  It does not produce design documentation, and it
does not produce decent user documentation without human effort.  Ada would
benefit from a similar tool.  (Wasn't a grad student at GWU working on one a
couple of years ago?)

-- Norman Cohen

Re: javadoc => adadoc?

[Brian Rogoff]

On Tue, 4 Aug 1998, Norman H. Cohen wrote:
... snip ...
> To summarize, javadoc is a handy tool which can provide effective
> component-user documentation when used in a conscientiously applied program
> of thorough commentary.  It does not produce design documentation, and it
> does not produce decent user documentation without human effort.  Ada would
> benefit from a similar tool.  (Wasn't a grad student at GWU working on one a
> couple of years ago?)

My own experience with the Java tools confirms this. If anything I found
that the psychological effect was the opposite of what was described;
programmers spent more time carefully documenting the code and keeping the 
user level documentation up to date with the javadoc tool. 

There are a few other tools which would be nice in an Ada environment,
like an Ada version of LCLint from the Larch toolkit (*), or a more 
general version of the SPARK analysis tools.

-- Brian

(*) http://www.sds.lcs.mit.edu/spd/larch/index.html

Re: javadoc => adadoc?

[Charles Hixson]

Brian Rogoff wrote:
> 
 ... snip ...
> ... I found
> that the psychological effect was the opposite of what was described;
> programmers spent more time carefully documenting the code and keeping the
> user level documentation up to date with the javadoc tool.
> 
> There are a few other tools which would be nice in an Ada environment,
> like an Ada version of LCLint from the Larch toolkit (*), or a more
> general version of the SPARK analysis tools.
> 
> -- Brian
> 
> (*) http://www.sds.lcs.mit.edu/spd/larch/index.html
Yes, the javaDoc structure seems to encourage keeping the documentation
(annotations) up to date.  The problem is that the extracted files are
HTML, and there doesn't seem to be any decent way of presenting them
off-line (and also, searching through html almost REQUIRES a search
engine).  What is needed is some way of marking index entries, and a way
to generate (rtf?) text with the index entries tied to page numbers
(which must be determined at print time).
-- 
Charles Hixson	charleshixson@earthling.net
(510) 464-7733	or chixso@mtc.dst.ca.us

Re: javadoc => adadoc?

[Peter Hermann]

Charles Hixson <charleshixson@earthling.net> wrote:
> engine).  What is needed is some way of marking index entries, and a way
> to generate

agreed

> (rtf?)

disagree (from the frying pan into the fire): rtf is a monster

> text with the index entries tied to page numbers
> (which must be determined at print time).

agree.

A simplified html is not that bad. 

I am still in search for a html-supporting utility which  would
support automatic page division and numbering with automatic indexing
and crossreferencing in order to ease the making of paper documentation
e.g. books with TOC, index, cross-refs.

-- 
Peter Hermann Tel+49-711-685-3611 Fax3758 ica2ph@csv.ica.uni-stuttgart.de
Pfaffenwaldring 27 Raum 114, D-70569 Stuttgart Uni Computeranwendungen
http://www.csv.ica.uni-stuttgart.de/homes/ph/
Team Ada: "C'mon people let the world begin" (Paul McCartney)

Re: javadoc => adadoc?

[Corey Minyard]

Peter Hermann <ica2ph@alpha1.csv.ica.uni-stuttgart.de> writes:

> Charles Hixson <charleshixson@earthling.net> wrote:
> > engine).  What is needed is some way of marking index entries, and a way
> > to generate
> 
> agreed
> 
> > (rtf?)
> 
> disagree (from the frying pan into the fire): rtf is a monster
> 
> > text with the index entries tied to page numbers
> > (which must be determined at print time).
> 
> agree.
> 
> A simplified html is not that bad. 
> 
> I am still in search for a html-supporting utility which  would
> support automatic page division and numbering with automatic indexing
> and crossreferencing in order to ease the making of paper documentation
> e.g. books with TOC, index, cross-refs.
> 

Use LaTeX and translate it to HTML with latex2html.  It does all these
things (and more).  I use it quite a bit.  Plus you can get very nice
printed documents from it.  Texinfo does this stuff, too, but I have
never used the texinfo to HTML tools.

-- 
Corey Minyard               Internet:  minyard@acm.org
  Work: minyard@nortel.ca       UUCP:  minyard@wf-rch.cirr.com

Re: javadoc => adadoc?

[Charles Hixson]

LaTex seems to be quite common on unix systems, but I haven't
encountered any LaTex tools on Windows.  I haven't been looking hard,
but they sure aren't obtrusive!
Maybe XML will develop into something that can handle this.
Texinfo I haven't heard of before (that I remember).  Is it related to
TEX? (tEX? however Knuth spelled it, anyway).

Corey Minyard wrote:
> 
> Peter Hermann <ica2ph@alpha1.csv.ica.uni-stuttgart.de> writes:
> 
> > Charles Hixson <charleshixson@earthling.net> wrote:
> > > engine).  What is needed is some way of marking index entries, and a way
> > > to generate
> >
> > agreed
> >
> > > (rtf?)
> >
> > disagree (from the frying pan into the fire): rtf is a monster
> >
> > > text with the index entries tied to page numbers
> > > (which must be determined at print time).
> >
> > agree.
> >
> > A simplified html is not that bad.
> >
> > I am still in search for a html-supporting utility which  would
> > support automatic page division and numbering with automatic indexing
> > and crossreferencing in order to ease the making of paper documentation
> > e.g. books with TOC, index, cross-refs.
> >
> 
> Use LaTeX and translate it to HTML with latex2html.  It does all these
> things (and more).  I use it quite a bit.  Plus you can get very nice
> printed documents from it.  Texinfo does this stuff, too, but I have
> never used the texinfo to HTML tools.
> 
> --
> Corey Minyard               Internet:  minyard@acm.org
>   Work: minyard@nortel.ca       UUCP:  minyard@wf-rch.cirr.com

-- 
Charles Hixson	charleshixson@earthling.net
(510) 464-7733	or chixso@mtc.dst.ca.us

Re: javadoc => adadoc?

[Samuel Tardieu]

>>>>> "Charles" == Charles Hixson <charleshixson@earthling.net> writes:

Charles> LaTex seems to be quite common on unix systems, but I haven't
Charles> encountered any LaTex tools on Windows.

TeX and LaTeX are available on Unices, Windows, Macintosh, and even
some other systems.

  Sam
-- 
Samuel Tardieu -- sam@ada.eu.org

Re: javadoc => adadoc?

[Simon Wright]

Corey Minyard <minyard@acm.org> writes:

> Use LaTeX and translate it to HTML with latex2html.  It does all these
> things (and more).  I use it quite a bit.  Plus you can get very nice
> printed documents from it.  Texinfo does this stuff, too, but I have
> never used the texinfo to HTML tools.

They work quite well. Personally I found the
texinfo-to-tex-to-postscript generates rather unsatisfactory and
uncontrollable document appearance, though.

Re: javadoc => adadoc?

[Matthew Heaney]

nelson@blaze-net.com writes:

> Are there any tools, public or otherwise, which can document an Ada
> program like Sun's javadoc?  I perused the usual Ada web sites, but
> didn't see anything (but there are a couple Ada html related tools).

I don't know if it supports the kind of documentation you have in mind,
but GRASP (I don't have the URL handy) provides a graphical display of
program structure.