Javadoc Header Example For Essay

Introduction

One of the nice things about Java is javadoc. The javadoc utility lets you put your comments right next to your code, inside your ".java" source files. When you're satisfied with your code and comments, you simply run the command, and your HTML-style documentation is automatically created for you.

A great thing about keeping your comments right next to your code is that it's much easier to keep the code and the documentation in sync. When you change the code, you change the comments, and run javadoc again. Very simple, very clean.

A working example

The code shown below provides a good example of what Javadoc comments look like. Forget for a while what this Java code is doing (it's not doing much anyway), and focus on the comments.

The first thing to notice is that javadoc comments begin with the symbol, and end with the symbol. This is a little bit different than the standard C or C++ style comments you might be used to seeing.

/** * Porsche.java - a simple class for demonstrating the use of javadoc comments. * @author Alvin Alexander * @version 1.0 * @see Automobile */ public class Porsche extends Automobile { protected String color; /** * Retrieve the value of color. * @return A String data type. */ public String getColor() { return color; } /** * Set the value of color. * @param newColor A variable of type String. */ public void setColor(String newColor) { color = newColor; } }

As you can see from the listing, javadoc also lets you define certain tags within your javadoc comments. Using these tags causes javadoc to create additional (and better) documentation on your behalf.

The table below briefly describes the purpose of the javadoc tags used in the sample source code shown above:

This tag lets you put the name of the code author into the documentation.
This tag is used to define parameters that are passed into a method.
This tag defines values that are returned from methods.
This tag creates "See Also:" output. You'll normally use this tag to refer to related classes.
This tag lets you define the version of the Java code you're developing. For instance, the code displayed in Listing 1 is considered to version 1.0.

This table shows the most commonly-used Javadoc tags.

How it works

There are only a few rules to worry about with javadoc. Keep these in mind when creating javadoc documentation in your code:

  • Javadoc comments only have meaning when they appear before a class, or before public or protected variables and methods.
  • The first line in a javadoc comment is a summary line. You'll see this description at the top of the HTML file for the class (i.e., ), and also in the file.

Also note that there is no need to begin each line of comments with an asterisk, as we've shown above. This is just a convention among many programmers, but not a standard. If you don't like this convention, just begin the comment with the characters, and end them with the characters.

Generating your Javadoc

After you've created your code, just run the javadoc command on your ".java" file, like this:

javadoc Porsche.java

When you do this, javadoc generates documentation in HTML format for all of your public classes, and your public and protected methods and variables. Based on the files you submit and the documentation within those files, javadoc creates four types of HTML files, as shown below:

packages.htmlA listing of each package you generated documentation for, and the classes they contain. In a small example like ours, this file won't contain any really useful information.
AllNames.htmlThis file contains an alphabetical index of all the variables (also referred to as fields) and methods you've defined.
tree.htmlA listing of all the classes you've generated documentation for, and where those classes fit in the class hierarchy.
Porsche.htmlThere will be one file of this type for each class defined. This file contains the actual documentation for the class.

This table provides brief descriptions of the files created when the javadoc command is run on your Java source files.

The output javadoc documentation

Well, that's enough about how it works. The best way to show how javadoc really works is to show the output it generates. Follow the links below to see the various output documentation files that javadoc created for the simple Porsche.java file shown earlier.

I think you'll agree with me after seeing the documentation that javadoc creates that it sure is a lot easier to let javadoc do the hard work. Think of the benefits:

  • The documentation sits right next to the code. Change the code, and it's easy to change the documentation.
  • Four different documentation file types are created for you. These are really needed with object-oriented programming.
  • The four different file types are all cross-linked, so clicking on a link in one file takes you directly to documentation in another file. Can you imagine doing this manually?

Javadoc is a great tool, and should be used with feelings of unbridled joy ;).

A method header combined with its associated javadoc form the specification, or contract, of a method. If the caller fulfills the stated requirements, then the method undertakes to fulfill its stated promises.

Using Javadoc acknowledges that there are two distinct questions a reader can ask about code:

  • what is this supposed to do? (answered only by the javadoc and method header)
  • how does it try to do it? (answered only by the implementation)

If javadoc is written correctly, then:

  • one can understand exactly what services are offered by a method ("what is this supposed this do?"), without having to look at its implementation ("how does it try to do it?"). Reading an implementation usually takes a lot more effort than reading javdoc.
  • the implementation can be checked for correctness versus the specification. That is, some bugs can be found just by reading the code, as opposed to executing it.
Oracle has published this style guide for writing javadoc comments.

Note that:

  • if you wish to provide high level descriptions, then you may use the file names (a conventional name) and to do so (see below).
  • javadoc is "inherited" - javadoc written for an interface method or an abstract method is automatically associated with corresponding concrete implementations
  • it's a common error to put the class level javadoc comment at the very start of a source file, before the statements. This is an error, since it must appear just above the class header.
Javadoc 1.4 has added many features, including:
  • the option allows user-defined custom tags. This feature can be used to implement common items such as , , or . (Oracle recommends placing a period somewhere in the custom tag, to avoid potential future conflicts with tags defined by Oracle.)
  • the option generates an HTML version of your source code, and links the javadoc to the source. (The source is presented without any syntax highlighting, but this remains a very nice feature.)
  • there is finer-grained control over how javadoc is inherited. The tag is useful here (warning: this is broken in JDK 1.4.0)
Javadoc 1.5 has these notable additions :
  • support for new language features, such as generics and annotations
  • the @literal and @code tags for ensuring text is not treated as markup

Example:

import java.math.BigDecimal; finalclass Guitar { Guitar(String aName, BigDecimal aPrice, Integer aNumStrings){ } String getName(){ returnnull; } BigDecimal getPrice(){ returnnull; } publicstaticfinal String KEY = "guitar"; void play(String aSongTitle){ } boolean tune(){ returntrue; } void lightOnFireAndSmashLikeAWildman(){ } }
Prefer to

Originally, an HTML file named was used to specify package level comments. That style is still available, but it's likely better to use instead:

  • it's shorter, since no boilerplate HTML is needed
  • the leading '*' on each line can be discarded, making it easy to paste in existing HTML
  • is the only place to annotate a package, if needed
The file is unusual since it doesn't contain a class. Indeed, the name is not a valid class name. Here is a simple example of its contents: /** Edit the roles attached to a user. */ package hirondelle.fish.access.role; Here is an example including an annotation for the package: /** Edit the settings attached to a user. */ @Unpublished package hirondelle.fish.access.user; Here is a final example without the leading '*' on every line: /** Maintain a list of Members in the Fish and Chips Club. An Active Member will be part of the RSVP list. When a Member is inactive, they will not appear on the RSVP listing. @author B. P. Hennessey @version 1.0 */ package hirondelle.fish.main.member;

See Also :

Document thread safety
Construct classes from the outside in
Design by Contract
Avoid basic style errors

Would you use this technique?

0 thoughts on “Javadoc Header Example For Essay

Leave a Reply

Your email address will not be published. Required fields are marked *