ADVANCED PROGRAMMING-2316205-3
Instructor: Dr. Asma Al-Shareef
Umm al-Quraa University
Notes for Lab4: Java Doc
What is Javadoc?
Javadoc is a tool used for generating Java code documentation in HTML format from Java source code which has
required documentation in a predefined format.
Following is a simple example where red part of the code represents Java comments:
/**
* The HelloWorld program implements an application that
* simply displays "Hello World!" to the standard output.
*
* @author Fulan
* @version 1.0
* @since
2015-03-31
*/
public class HelloWorld {
public static void main(String[] args) {
// Prints Hello, World! on standard output.
System.out.println("Hello World!");
}
}
You can include required HTML tags inside the description part, For example, below example makes use of
<h1>....</h1> for heading and <p> has been used for creating paragraph break:
/**
* <h1>Hello, World!</h1>
* The HelloWorld program implements an application that
* simply displays "Hello World!" to the standard output.
* <p>
* Giving proper comments in your program makes it more
* user friendly and it is assumed as a high quality code.
*
*
* @author Fulan
* @version 1.0
* @since
2015-03-31
*/
public class HelloWorld {
public static void main(String[] args) {
// Prints Hello, World! on standard output.
System.out.println("Hello World!");
}
}
The javadoc Tags:
Javadoc tags are keywords recognized by Javadoc which define the type of information that follows.
The javadoc tool recognizes many tags, we will just concentrate on the following:
pg. 1
1435/1436
ADVANCED PROGRAMMING-2316205-3
Instructor: Dr. Asma Al-Shareef
Umm al-Quraa University
Tag
Description
Syntax
@author
Adds the author of a class.
@author name-text
@deprecated
Adds a comment indicating that this API
should no longer be used.
@deprecated deprecatedtext
@exception
Adds a Throws subheading to the
generated documentation, with the classname and description text.
@exception class-name
description
@param
Adds a parameter with the specified
parameter-name followed by the specified
description to the "Parameters" section.
@param parameter-name
description
@return
Adds a "Returns" section with the
description text.
@return description
@see
Adds a "See Also" heading with a link or
text entry that points to reference.
@see reference
@serial
Used in the doc comment for a default
serializable field.
@serial field-description |
include | exclude
@since
Adds a "Since" heading with the specified
since-text to the generated documentation.
@since release
@throws
The @throws and @exception tags are
synonyms.
@throws class-name
description
@version
Adds a "Version" subheading with the
specified version-text to the generated docs
when the -version option is used.
@version version-text
Example:
Following program uses few of the important tags available for documentation comments. You can make use of
other tags based on your requirements.
The documentation about the AddNum class will be produced in HTML file AddNum.html but same time a master
file with a name index.html will also be created.
import java.io.*;
/**
* <h1>Add Two Numbers!</h1>
* The AddNum program implements an application that
* simply adds two given integer numbers and Prints
* the output on the screen.
* <p>
* <b>Note:</b> Giving proper comments in your program makes it more
* user friendly and it is assumed as a high quality code.
*
* @author Fulan
pg. 2
1435/1436
ADVANCED PROGRAMMING-2316205-3
Instructor: Dr. Asma Al-Shareef
Umm al-Quraa University
* @version 1.0
* @since
2015-03-31
*/
public class AddNum {
/**
* This method is used to add two integers. This is
* a the simplest form of a class method, just to
* show the usage of various javadoc Tags.
* @param numA This is the first paramter to addNum method
* @param numB This is the second parameter to addNum method
* @return int This returns sum of numA and numB.
*/
public int sum(int numA, int numB) {
return numA + numB;
}
/**
* This is the main method which makes use of addNum method.
* @param args Unused.
* @return Nothing.
* @exception IOException On input error.
* @see IOException
*/
public static void main(String args[]) throws IOException
{
AddNum obj = new AddNum();
int sum = obj.sum(10, 20);
System.out.println("Sum of 10 and 20 is :" + sum);
}
}
Now, process above AddNum.java file using javadoc utility as follows:
$ javadoc AddNum.java
pg. 3
1435/1436
