Java Reference
In-Depth Information
It should be noted that this “feature” was introduced to work around a bad programming
practice. You might want to use it when you would otherwise be tempted to declare local
copies of the constants, or when you are tempted to abuse the inheritance as mentioned
earlier. But, in general, we recommend that you avoid this where possible, and use qualified
constants.
Javadoc
Javadoc is a very simple, yet powerful, tool that helps programmers provide API documenta-
tion for other programmers.
The default Javadoc tool is very simple. It parses your source code, looking for special
comments. It then generates HTML documentation based on that. To make this easier to
understand, let's start with some sample Javadoc comments, and describe them:
/**
* The <b>main</b> starting point for this application.
* Instantiates an instance of this class, and runs it.
*
* @param args an array containing the command line arguments.
* @throws IOException if files cannot be created
*/
public static void main(String[] args) throws IOException {
// ...
A Javadoc comment starts with the special comment start indicator of
/**
, and continues until
the comment closing indicator of
*/
. Tags are noted by the at symbol (
@
). All text from the
comment start indicator through to the first tag is included directly in the generated output.
Javadoc will ignore unknown tags and plain text after
any tag
has been found up until the next
known tag, or the end of the doc comment—this bit of magic is how XDoclet can work.
The Javadoc code above produces the following HTML:
<A NAME="main(java.lang.String[])"><!-- --></A><H3>
main</H3>
<PRE>
public static void <B>main</B>(java.lang.String[] args)
throws java.io.IOException</PRE>
<DL>
<DD>The <b>main</b> starting point for this application.
Instantiates an instance of this class, and runs it.
<P>
<DD><DL>
<DT><B>Parameters:</B><DD><CODE>args</CODE> - an array containing the command
line arguments.
<DT><B>Throws:</B>
<DD><CODE>java.io.IOException</CODE> - if files cannot be created</DL>
</DD>
</DL>
