Download Using JavaDoc - Villanova Computer Science

JAVA DOC - TOOL provided in the jdk
Java Doc is a documentation tool that allows you to create an html page of all your methods like
those that you see when you look up a java class in the Java API. See example javadoc at bottom of
page 4 and 6 .
Since NetBeans and Eclipse will generate the html page for you (and those instructions are here for
Eclipse and NetBeans), we will use them. However, I want you to know how to do it yourselves. You
must do it in at least two of your classes in your GUI competition project using javadoc. You will hand
in one html page in your project folder. You must also fully document all your other methods and
classes and there will be 3 points deducted if the documentation is not complete. After doing this in
Eclipse, do again from the command prompt as described below.
Instructions for Eclipse:
TO GENERATE JavaDoc IN ECLIPSE:
Open up a project you have done.e.g. HPAIr and open a file in it , e.g City
Go to the Project Button and choose “generate javadoc”:
A window opens as above and you need to enter the javadoc command - i.e, specify where the .exe
file is to run javadoc: e.g on my computer it located at;
C:\Program Files (x86)\Java\jdk1.6.0_18\bin\javadoc.exe
1
Where the above is the location of the JDK on your computer,
In the bin directory. You can scroll down and find the javadoc.exe executable file, click on it
2 Next , Select the project you want to work in from the list in the box “Select Types for which
javadoc etc” - choose the project you are going to generate javadoc on – e.g. this should be a project
already opened in the Eclipse window.
3. Next ,Select the destination where you want to send the html file which will be created
This should be the workspace that you have already designated for all your projects. E .g.
This is where it is on my computer - you must include the “doc” directory. ( It might show up already).
C:\Users\Cathy\workspace\HPAIr2\doc // this is where my output goes from Eclipse
4. Then navigate to the above workspace directory that you specified when setting up Eclipse,
When you get to the doc folder in this directory
you will see a folder for HPAir - (folder I used)
And look for an .html file that will display all the methods etc like you see when you look up a class
in API on Google.
Click on the .html file and your javadoc list of methods for City will be displayed in a browser
See display below on Page 4 to view sample output produced by javadoc and what it means.
GENERATING COMMENTS FOR CLASSES AND METHODS.
It is easiest to generate the comments when you are building the project from the beginning but
you can also generate comments afterward:
Eclipse can generate Javadoc comments for classes and methods after the class has been
created by doing the following
1.
2.
3.
4.
Place the cursor in the text of one of your class’s method declaration.
Click->Source->”Generate Element Comment”
It might also have according to version: “generate javadoc comment”
Javadoc comments with appropriate tags are generated, but you still have to write
the descriptions inside the tags
Example JavaDoc documentation
/**
* Returns an Image object that can then be painted on the screen.
* The url argument must specify an absolute {@link URL}. The name
* argument is a specifier that is relative to the url argument.
* <p>
2
*
*
*
*
*
*
*
*
*
This method always returns immediately, whether or not the
image exists. When this applet attempts to draw the image on
the screen, the data will be loaded. The graphics primitives
that draw the image will incrementally paint on the screen.
@param url
@param name
@return
@see
an absolute URL giving the base location of the image
the location of the image, relative to the url argument
the image at the specified URL
Image
public Image getImage(URL url String name)
{
try {
return getImage(getURL(name));
} catch (Exception e) {
return null;
}
}
protected URL getURL(String filename) {
URL codeBase = this.getCodeBase();
URL url = null;
try {
url = new URL(codeBase, filename);
} catch (java.net.MalformedURLException e) {
System.out.println("Couldn't create image: badly specified URL");
return null;
}
return url;
}
}
Notes: Explanation of








The resulting HTML from running Javadoc is shown above
Each line above is indented to align with the code below the comment.
The first line contains the begin-comment delimiter (/**).
Starting with Javadoc 1.4, the leading asterisks are optional.
Write the first sentence as a short summary of the method, as Javadoc automatically
places it in the method summary table (and index).
Notice the inline tag {@link URL}, which converts to an HTML hyperlink pointing to the
documentation for the URL class.
If you have more than one paragraph in the doc comment, separate the paragraphs with a
<p> paragraph tag, as shown.
Insert a blank comment line between the description and the list of tags, as shown.
3


The first line that begins with an "@" character ends the description. There is only one
description block per doc comment;
The last line contains the end-comment delimiter (*/) Note that unlike the begincomment delimiter, the end-comment contains only a single asterisk.
For examples on how to annotate your class so that your html file will show important
information see:
http://students.cs.byu.edu/~cs240ta/fall2012/tutorials/javadoctutorial.html
So lines won't wrap, limit any doc comment lines to 80 characters.
Here is what the html page would look like after running the Javadoc tool:
Reverse3
public Reverse3()
Method Detail
getImage
public java.awt.Image getImage(java.net.URL url,
java.lang.String name)
Returns an Image object that can then be painted on the screen. The url argument must
specify an absolute URL. The name argument is a specifier that is relative to the url
argument.
This method always returns immediately, whether or not the image exists. When this
applet attempts to draw the image on the screen, the data will be loaded. The graphics
primitives that draw the image will incrementally paint on the screen.
Overrides:
getImage in class java.applet.Applet
Parameters:
url - an absolute URL giving the base location of the image
name - the location of the image, relative to the url argument
Returns:
the image at the specified URL
See Also:
Image
getURL
protected java.net.URL getURL(java.lang.String filename)
4
II. Below are the steps you need to take to create that documentation yourself from the command
prompt.
You will do the above steps from the command prompt .
You must navigate to the folder where your project is. The command to change to another directory
is:
cd absolute path
e.g. cd c:\EddieFiles\doc)
You should create a “doc” directory . (If doc is not in the same folder as your project
you will have to use its full path name, e.g. c:\EddieFiles\doc)
To reiterate:
There are three easy steps to having the HTML documentation for a class generated by javadoc.
These steps are described above.
Step 1. Make a directory for HTML documentation.
Make a directory within the directory in which the .java files are stored. You need the .java files
and .class files to produce the javdoc documentation.
5
Step 2. Execute javadoc.
Execute the javadoc program. (FIRST YOU MUST HAVE THE FILEs COMPILED).
Javadoc is included with the Java Development Kit and so it should be available in the same
way you run javac and java from the command prompt.
When you compile classes with javac, you execute the command javac followed by the name of
the class . For example, in the folder which contains the file Reverse3.java
javac Reverse3.java. // compiles Reverse2
Similarly, when you generate javadoc for a class definition, you execute the command
javadoc Reverse3.java –d doc
( where doc is the name of the directory where you will store your javadoc files.)
you must use -d and then the relative directory path to the directory – doc- in which you
want the resulting HTML file(s) stored. The relative path is not needed if the doc folder is in the
same folder as your java files.
Step 3. View javadoc results. Use your browser and open the javadoc html page in your doc
directory.
In NetBeans:
Open your project for HPAir(or some other project) or if it is open to generate javadoc :.
Under run, choose
“generate javadoc” for the whole project
NetBeans creates the javadoc html file which it will load in a browser window. In the browser window
to the left, the html file is displayed and you can then save that html file to your folder with the other
files
6