File comments for Java

The following is referenced from http://wiki.jikexueyuan.com/project/java/documentation.html:

The Java language supports three forms of annotation:

Notes	Description
/*text*/	The compiler ignores */* to all things
Text	The compiler ignores everything from//to the end of a line
/** Documentation */	This is a document comment and is generally called Doc comment. The JDK Javadoc tool uses the DOC comment when preparing to automatically prepare the build file

First, what is Javadoc?

Javadoc is a tool that comes with the JDK and is used to generate Java source code files from a document that requires a predefined format to a Java code file in HTML format.

Here is a simple example where the red part represents the Java comment:

/*** The HelloWorld program implements a application that* simply displays "Hello world!" to the standard output.** @ Author  Zara ali* @version 1.0* @since   2014-03-31 */Publicclass  HelloWorld {     publicstaticvoid  main (string[] args) {        //Prints Hello, world! On standard output.        System.out.println ("Hello world!" );    }}

You can include the required HTM tags in the description section, for example, the following example uses

/*** Hello, world! * The HelloWorld program implements a application that* simply displays "Hello world!" to the Standar D output.* <p>* Giving Proper comments in your program makes it more* user friendly and it is assumed as a High quality code.* * *@authorZara ali*@version1.0*@since2014-03-31*/ Public classHelloWorld { Public Static voidMain (string[] args) {//Prints Hello, world! on standard output.System.out.println ("Hello world!"); }}

Second, Javadoc label

The Javadoc tag is a Javadoc recognized keyword that defines the type of information below.

The Javadoc tool recognizes the following tags:

label	Description	Grammar
@author	Add the author of a class	@author Name-text
{@code}	Do not convert text to HTML tags and nested Java tags and display it in a code font	{@code text}
{@docRoot}	Represents the relative path from any build page to the root of the generated document	{@docRoot}
@deprecated	Add a comment suggesting that the API should no longer be used	@deprecated Deprecated-text
@exception	Add a subtitle to the generated document with the class name and description text	@exception class-name Description
{@inheritDoc}	Inherit comments from the most recent inheritable class or an implemented interface	Inherits a comment from the immediate surperclass.
{@link}	Insert an online link with a visible text label that points to a specific package, class, or document that references the member name of the class	{@link Package.class#member label}
{@linkplain}	Same as {@link}, except for linked labels with plain text instead of code fonts	{@linkplain Package.class#member label}
@param	Add a parameter to the parameters area with a specific parameter name followed by a specific description	@param parameter-name Description
@return	Add a "Returns" area with descriptive text	@return Description
@see	Add the title "See Also" with links or text portals to references	@see Reference
@serial	Used in text annotations of the default serialization field	@serial field-description	Include	Exclude
@serialData	Record data written by the WriteObject () or writeexternal () method	@serialData data-description
@serialField	Record a Objectstreamfield ingredient	@serialField field-name Field-type field-description
@since	Add a "Since" heading with a specific Since text to the generated document	@since Release
@throws	@throw and @exception tags are synonyms	@throws class-name Description
{@value}	When {@value} is used in a text comment of a static field, it shows the value of that constant	{@value Package.class#field}
@version	Add a "version" subtitle to the generated text with a specific Version text when the-version option is used	@version Version-text

Example:

The following program uses some important tags to make documentation comments. Other labels can be leveraged based on demand.

Documents about the Addnum class will be created by the HTML file addnum.html, but a master file named Index.html will be created as well.

ImportJava.io.*;/*** @authorZara ali*@version1.0*@since2014-03-31*/ Public classAddnum {/*** This method was used to add a integers.   This was * a simplest form of a class method, just to * show the usage of various Javadoc Tags. * @paramNumA paramter to Addnum method *@paramNumB The second parameter to Addnum method *@returnint This returns sum of NumA and NumB. */    Public intAddnum (intNumaintNumB) {      returnNumA +NumB; }   /*** This is the main method, which makes use of Addnum method. * @paramargs Unused. * @returnNothing . * @exceptionIOException on input error. * @seeIOException*/    Public Static voidMain (String args[])throwsioexception {addnum obj=NewAddnum (); intsum = Obj.addnum (10, 20); System.out.println ("Sum of Ten and" is: "+sum); }}

Now, work with the Addnum.java file that uses Javadoc:

$ javadoc addnum.javaloading source file Addnum.java ... Constructing Javadoc information ... Standard Doclet version1.7. 0_51building Tree forAll the packages and classes ... Generating/addnum.html ... Addnum.java:36:warning-@returnTag cannot be used on method withvoid returntype. Generating/ Package-frame.html ... Generating/ Package-summary.html ... Generating/ Package-tree.html ... Generating/constant-values.html ... Building Index forAll the packages and classes ... Generating/overview-tree.html ... Generating/index-all.html ... Generating/deprecated-list.html ... Building Index forAll classes ... Generating/allclasses-frame.html ... Generating/allclasses-noframe.html ... Generating/index.html ... Generating/help-doc.html ...1warning$

If you are using JDK 1.7 then Javadoc does not generate STYSHEET.CSS, so it is recommended to download and use the standard stylesheet from Http://docs.oracle.com/javase/7/docs/api/stylesheet.css.

File comments for Java