Java Doc

JavaDoc is a BarelyLiterateProgramming system for JavaLanguage. The language is limited, but it is standard and reasonably accessible.

The Java standard APIs are shown in HTML output at http://java.sun.com/j2se/1.5.0/docs/api/index.html. Guidelines for writing doc comments appear at http://java.sun.com/products/jdk/javadoc/writingdoccomments/index.html.

An example (perhaps not a good one) of JavaDoc comments on a method: 

/**
 * Display an exception in a relatively user-friendly dialog box.
 * The user can display a traceback by pressing a button.
 *
 * @param owner Owner of the dialog box, or null for a top-level
 *dialog.
 * @param cause The exception that caused the problem. May not be
 *null.
 * @param title Title for the dialog box, or null for a default
 *title.
 * @param msgA user-friendly explanation of the problem, or null
 *for no explanation.
 * @param options Bitmask of option buttons to display
 *
 * @returnAn option value, or zero if the window was closed
 *with no option selected.
 **/
 static public long showException(Frame owner,
 Throwable cause,
 String msg,
 String title,
 long options)
 {
 //....
 }

What kinds of things do you want JavaDoc to do?

The features I lack the most in JavaDoc are IncrementalSearch (a-la emacs), and SortByReturnType? (Sort of a poor-man's MethodFinder?). I just keep getting the feeling that HTML just isn't good enough base for JD. -- AvivEyal

I needed a JavaDoc based printed document, so I created a LaTeX2e generating java2 doclet[1]. I am still looking for an RTFDoclet that does windows help file format RTF. -- GreggWonderly

Before Doclet's existed, I added some of my own "JavaDoc" keywords to my source code to denote traceability back to use-cases and CRC cards. I had keywords like @responsibility and @collaborators for CRC cards, and @usecase, @pre, @post, and @step for use-cases. Then I had a quickie perl-script generate the CRC cards and Use-cases in HTML format (with appropriate hyperlinks between each, and to a graphics file for the use-case diagram). After that, I didnt maintain the CRC cards or use-cases separately from the code. They were all part of the same "compound" document. If Doclets had existed back then I would have done it that way instead. And if I had the time these days I'd convert my stuff to use one :-) -- BradAppleton

Most JavaDoc I see in code is useless, and says little more about the code than the types already available from the method signature (assuming Java). The above example is good in that it mentions what null paramater values mean, however some of it can be directly deduced from the paramater names and it tells you nothing about how to construct the bit mask for the option buttons (probably one of the most frustrating things which you encounter all of the time). The author did qualify his example - but its very easy to write JavaDoc for the sake of it rather than just writing better code. I believe XP strives to right (write?) as little JavaDoc as possible. I also find raw java doc very difficult to read when in a coding environment, although some environments do render it for you (I believe Visual J++ does, sadly Visual Age doesn't) -- TimMackinnon

That was an example from some of my code, and I quoted it because it shows how I feel ambivalent about JavaDoc. I would prefer to avoid MethodComment?s and use obvious names rather than write JavaDoc. At the same time, for times when external documentation is required - for example for people using a library, or to explain what null does - it's a nice way to do it. In fact, the JavaDoc paradigm of stripping documentation completely out of the context in which it is used seems almost _harmful_ to developing understandable code. Some kind of synthesis of the BarelyLiterateProgramming tools is probably best. -- MartinPool

Critique: You didn't explain what the bit values were for options, perhaps the only information worth knowing for this method.

At one point - I think it was on the XP mailing list - Ward commented that the thing he didn't like about JavaDoc is that you can't click on a method description and see the source code for it.

JavaDoc starting JDK 1.4 has the ability to include source using the option linksource.

I've been writing my class headers in C++ as I normally do. Small number of lines, yet dense information (tight, in other words). Eventually, I have to convert the whole mess to JavaDoc, but I'm dreading it. I don't like JavaDoc because it breaks the fundamental principle I have for when I write class headers: present useful information right away. JavaDoc increases the amount of useless space in the header that defeats any attempt at grouping semantically related methods together. I think on my monitor I can fit maybe four methods to a screen with JavaDoc, whereas I'm used to putting the whole class on my screen. And we're not talking about trivial classes either.

Before you ask, an example of my MethodComments: 

// ---------------------------------------------------- FOO


// Gets the value of the foo of the given type (eFoo).
// The value's meaning depends on the given foo.
UINT32 getFoo( CFoo::TYPE eFoo );


// Sets the foo of the given type (eFoo) with the given 
// value. The value's meaning depends on the given foo.
void setFoo( CFoo::TYPE eFoo, UINT32 uValue );


// Resets the foo to the default value. This usually means 
// inherit its value from the nearest ancestor in which it is
// set. However, if no such ancestor exists, it is reset to
// the Bar default (cf. http://www.example.com/spec/Baz).
void resetFoo( CFoo::TYPE eFoo );
-- SunirShah

As part of my ongoing adventure in JavaDoc, I wrote a C++/JavaDoc to FrameMaker parser/generator in a few hundred lines of Perl. One advantage of this is that I am able to do some simple WikiSyntax translations on the JavaDoc to make it look pretty. So far, I only do monospace conversion for indented text. I can also add new commands if I feel like it. I can also emit class descriptions in XML if I feel like it. I can do lots of things. Perl is fun. Java(doc) is not. -- SunirShah

Couldn't you just use JavaDoc this way? After all, you don't have to comment things you don't feel are essential... 

/** Gets the value of the foo of the given type (eFoo).
The value's meaning depends on the given foo. */
int getFoo( CFoo.TYPE eFoo ) {...}


/** Sets the foo of the given type (eFoo) with the given 
value. The value's meaning depends on the given foo. */
void setFoo( CFoo.TYPE eFoo, int uValue ) {...}


/** Resets the foo to the default value. This usually means 
inherit its value from the nearest ancestor in which it is
set. However, if no such ancestor exists, it is reset to
the Bar default (cf. http://www.example.com/spec/Baz). */
void resetFoo( CFoo.TYPE eFoo ) {...}
-- ChuckMcCorvey

Using JavaDoc commands ala @param, @return, @see look nicer on separate lines. They may even be required to be on separate lines. Half the point of JavaDoc is using those commands, for whatever reason.

True, but you can't say that the Javadoc example is less concise or conveys less information than the C++ version. You are never required to use @param, @return, etc (except perhaps by coding conventions). The standard doclet does give warnings, but you can ignore them. Then you can restrict the use of @param, @see, etc to those circumstances where they benefit you. -- RobertWatkins

The primary use of JavaDoc is when you're writing code that uses class X, not when you're coding class X itself. Even with classes that I wrote, I generally refer to the JavaDoc instead of the source code when using a class. Output that's formatted and organized is more accessible than plain-text declarations. With good InformationHiding and JavaDoc, other people who use my classes should never have a reason to look at my source code.

However, my private methods omit the @param and @return information. Once you're already looking at the code, it's easier to read the declaration directly. -- JaredLevy

If you want to generate JavaDoc-like documentation in C++, try DoxyGen.

-- JeanLucBonnafoux?

The jmldoc tools of the JML project [ http://www.jmlspecs.org ] is a "backwards" way of utilizing the javadoc API for producing javadoc-like pages. The JML project has a syntax for adding specifications within specially formatted comments to java code, as well as tools that parse those comments (and the Java code) to do typechecking, runtime assertion checking, testcase and oracle generation, static verification - and documentation. The jmldoc tool produces the regular javadoc html pages, but with information about the specifications inserted into the pages. The javadoc API is useful for this purpose.

However, most (I think) javadoc doclets utilize the supplied library to obtain a parse tree of the Java source and then customize the output. In the case of jmldoc, we already have a parse tree - so we created glue classes to match those to what the Javadoc API would produce and then pass thaat in to the API so that appropriate HTML pages are produced. By adding HTML content to the usual javadoc comment, we get the specifications in the output.

This works well in one sense - that we automatically get HTML output consistent with current javadoc style, and jmldoc is a drop-in replacement, pretty much, for javadoc. What does not work so well is that the API as seen from this direction is not very stable.

-- DavidCok?

Another missing feature is InterNationalization?. At the moment, the sun RFE page is full of people wanting Chinese language API doco. Luckily, the doclet facility allows you to build add-ons which will do the job, but it remains the case that there is no standard way to supply multilingual API doco.

Mind you ... keeping multilingual API doco up to date would be a major headache in its own right.

-- PaulMurray

IDE specific information

EditText of this page (last edited August 29, 2011) or FindPage with title or text search