2. JavaDoc Tags
You can add a lot of information to a code, using comments. But they are not taken into account by the Javadoc tool. But Sun has done some things, there are comments made specially for the Javadoc, and more better, tags that allow precise detailing information about each class, each method, variables etc. As you all know, there are three types of comments in Java. The comments on lines, comments on several lines, and Javadoc comments.
Here is an example showing the three types of comment
Code:
/**
* This is a Comment for Javadoc.
* It begins by a slash followed of two stars.
* Each row must then begin by a star.
* Finally, it finished by a star followed the slash.
*/
protected Vector<Zero> getVectorAmis(){
// This is a Comment on a row
Vector<Zero> vec = new Vector<Zero>();
/* This is a Comment on
many lines */
for (Z Zero: list){
vec.add(z);
}
return vec;
}
So all the information we find will be in the Javadoc comment. It should be on the line immediately before the class name, method, or variable.
Javadoc tags are nine in number:
@ param
@ return
@ throws
@ author
@ version
@ see
@ since
@ serial
@ deprecated
For more information on this, refer to the style guide in SUN. You can find it on their official site.
More detailed information about JavaDoc
@ param: parameters of the method
The @ param tag is used to learn the parameter of the method. Behind the tag, it must learn the name parameter (its type will be automatically included in the Javadoc).
Here is an source code example
Code:
/**
* Met today the lev of Member.
* * @ param lev
* The new lev of Member.
*/
protected void setlev(SDZLevel lev) {
this. lev = lev;
}
@ return: the object returned by the method
The @ return tag is used to inform the object returned by the method.
Here is an source code example
Code:
/**
* Returns the lev of zero.
*
* @ return A Instance of SDZLevel, who corresponds to lev of Member on SDZ.
*/
Public SDZLevel getLevel() {
return lev;
}
@ throws: exceptions propagated
The @ throws tag indicates the presence of an exception to be propagated if it rises. We must specify the type of exception and the reason for the exception.
Here is an source code example
Code:
/**
* Returns the address of profile of Zero.
*
* @ return the URL of profile of Zero, generated to from of l'id of Zero.
*
* @ throws MalformedURLException If never url is evil formed.
*/
Public URL getURLProfil() throws MalformedURLException{
URL url = new URL("http://www.example.com/membres-258-"+id+". html");
return url;
}
Bookmarks