From mboxrd@z Thu Jan 1 00:00:00 1970 X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) on polar.synack.me X-Spam-Level: X-Spam-Status: No, score=-1.9 required=5.0 tests=BAYES_00 autolearn=ham autolearn_force=no version=3.4.4 X-Google-Language: ENGLISH,ASCII-7-bit X-Google-Thread: 103376,3334f982144a667d X-Google-Attributes: gid103376,public From: "Norman H. Cohen" Subject: Re: javadoc => adadoc? Date: 1998/08/04 Message-ID: <6q7773$mhi$1@mdnews.btv.ibm.com> X-Deja-AN: 377837880 References: <6ptlbe$k3$1@nnrp1.dejanews.com> <6pvslq$poo@drn.newsguy.com> <6q4k5q$10uo$1@mdnews.btv.ibm.com> <35C5DAC4.F68DA421@earthling.net> <1998Aug4.073510.1@eisner> X-MimeOLE: Produced By Microsoft MimeOLE V4.72.3110.3 Organization: IBM Microelectronics Division Newsgroups: comp.lang.ada Date: 1998-08-04T00:00:00+00:00 List-Id: Larry Kilgallen wrote in message <1998Aug4.073510.1@eisner>... >In article , 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 len 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 * -1 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