* javadoc => adadoc? @ 1998-07-31 0:00 nelson 1998-08-01 0:00 ` Matthew Heaney 1998-08-01 0:00 ` nabbasi 0 siblings, 2 replies; 15+ messages in thread From: nelson @ 1998-07-31 0:00 UTC (permalink / raw) 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 ^ permalink raw reply [flat|nested] 15+ messages in thread
* Re: javadoc => adadoc? 1998-07-31 0:00 javadoc => adadoc? nelson @ 1998-08-01 0:00 ` Matthew Heaney 1998-08-01 0:00 ` nabbasi 1 sibling, 0 replies; 15+ messages in thread From: Matthew Heaney @ 1998-08-01 0:00 UTC (permalink / raw) 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. ^ permalink raw reply [flat|nested] 15+ messages in thread
* Re: javadoc => adadoc? 1998-07-31 0:00 javadoc => adadoc? nelson 1998-08-01 0:00 ` Matthew Heaney @ 1998-08-01 0:00 ` nabbasi 1998-08-03 0:00 ` Norman H. Cohen 1 sibling, 1 reply; 15+ messages in thread From: nabbasi @ 1998-08-01 0:00 UTC (permalink / raw) 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 ^ permalink raw reply [flat|nested] 15+ messages in thread
* Re: javadoc => adadoc? 1998-08-01 0:00 ` nabbasi @ 1998-08-03 0:00 ` Norman H. Cohen 1998-08-03 0:00 ` Charles Hixson 0 siblings, 1 reply; 15+ messages in thread From: Norman H. Cohen @ 1998-08-03 0:00 UTC (permalink / raw) 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 ^ permalink raw reply [flat|nested] 15+ messages in thread
* Re: javadoc => adadoc? 1998-08-03 0:00 ` Norman H. Cohen @ 1998-08-03 0:00 ` Charles Hixson 1998-08-04 0:00 ` Robert Dewar 0 siblings, 1 reply; 15+ messages in thread From: Charles Hixson @ 1998-08-03 0:00 UTC (permalink / raw) 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 ^ permalink raw reply [flat|nested] 15+ messages in thread
* Re: javadoc => adadoc? 1998-08-03 0:00 ` Charles Hixson @ 1998-08-04 0:00 ` Robert Dewar 1998-08-04 0:00 ` Larry Kilgallen 0 siblings, 1 reply; 15+ messages in thread From: Robert Dewar @ 1998-08-04 0:00 UTC (permalink / raw) 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! ^ permalink raw reply [flat|nested] 15+ messages in thread
* Re: javadoc => adadoc? 1998-08-04 0:00 ` Robert Dewar @ 1998-08-04 0:00 ` Larry Kilgallen 1998-08-04 0:00 ` Norman H. Cohen 0 siblings, 1 reply; 15+ messages in thread From: Larry Kilgallen @ 1998-08-04 0:00 UTC (permalink / raw) 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 ^ permalink raw reply [flat|nested] 15+ messages in thread
* Re: javadoc => adadoc? 1998-08-04 0:00 ` Larry Kilgallen @ 1998-08-04 0:00 ` Norman H. Cohen 1998-08-04 0:00 ` Brian Rogoff 0 siblings, 1 reply; 15+ messages in thread From: Norman H. Cohen @ 1998-08-04 0:00 UTC (permalink / raw) 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 ^ permalink raw reply [flat|nested] 15+ messages in thread
* Re: javadoc => adadoc? 1998-08-04 0:00 ` Norman H. Cohen @ 1998-08-04 0:00 ` Brian Rogoff 1998-08-04 0:00 ` Charles Hixson 0 siblings, 1 reply; 15+ messages in thread From: Brian Rogoff @ 1998-08-04 0:00 UTC (permalink / raw) 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 ^ permalink raw reply [flat|nested] 15+ messages in thread
* Re: javadoc => adadoc? 1998-08-04 0:00 ` Brian Rogoff @ 1998-08-04 0:00 ` Charles Hixson 1998-08-17 0:00 ` Peter Hermann 0 siblings, 1 reply; 15+ messages in thread From: Charles Hixson @ 1998-08-04 0:00 UTC (permalink / raw) 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 ^ permalink raw reply [flat|nested] 15+ messages in thread
* Re: javadoc => adadoc? 1998-08-04 0:00 ` Charles Hixson @ 1998-08-17 0:00 ` Peter Hermann 1998-08-17 0:00 ` Corey Minyard 0 siblings, 1 reply; 15+ messages in thread From: Peter Hermann @ 1998-08-17 0:00 UTC (permalink / raw) 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) ^ permalink raw reply [flat|nested] 15+ messages in thread
* Re: javadoc => adadoc? 1998-08-17 0:00 ` Peter Hermann @ 1998-08-17 0:00 ` Corey Minyard 1998-08-18 0:00 ` Charles Hixson 1998-08-26 0:00 ` Simon Wright 0 siblings, 2 replies; 15+ messages in thread From: Corey Minyard @ 1998-08-17 0:00 UTC (permalink / raw) 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 ^ permalink raw reply [flat|nested] 15+ messages in thread
* Re: javadoc => adadoc? 1998-08-17 0:00 ` Corey Minyard @ 1998-08-18 0:00 ` Charles Hixson 1998-08-19 0:00 ` Samuel Tardieu 1998-08-26 0:00 ` Simon Wright 1 sibling, 1 reply; 15+ messages in thread From: Charles Hixson @ 1998-08-18 0:00 UTC (permalink / raw) 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 ^ permalink raw reply [flat|nested] 15+ messages in thread
* Re: javadoc => adadoc? 1998-08-18 0:00 ` Charles Hixson @ 1998-08-19 0:00 ` Samuel Tardieu 0 siblings, 0 replies; 15+ messages in thread From: Samuel Tardieu @ 1998-08-19 0:00 UTC (permalink / raw) >>>>> "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 ^ permalink raw reply [flat|nested] 15+ messages in thread
* Re: javadoc => adadoc? 1998-08-17 0:00 ` Corey Minyard 1998-08-18 0:00 ` Charles Hixson @ 1998-08-26 0:00 ` Simon Wright 1 sibling, 0 replies; 15+ messages in thread From: Simon Wright @ 1998-08-26 0:00 UTC (permalink / raw) 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. ^ permalink raw reply [flat|nested] 15+ messages in thread
end of thread, other threads:[~1998-08-26 0:00 UTC | newest] Thread overview: 15+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 1998-07-31 0:00 javadoc => adadoc? nelson 1998-08-01 0:00 ` Matthew Heaney 1998-08-01 0:00 ` nabbasi 1998-08-03 0:00 ` Norman H. Cohen 1998-08-03 0:00 ` Charles Hixson 1998-08-04 0:00 ` Robert Dewar 1998-08-04 0:00 ` Larry Kilgallen 1998-08-04 0:00 ` Norman H. Cohen 1998-08-04 0:00 ` Brian Rogoff 1998-08-04 0:00 ` Charles Hixson 1998-08-17 0:00 ` Peter Hermann 1998-08-17 0:00 ` Corey Minyard 1998-08-18 0:00 ` Charles Hixson 1998-08-19 0:00 ` Samuel Tardieu 1998-08-26 0:00 ` Simon Wright
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox