Java Document Comment writing format

Java documentation Comments are written in Java document annotations on the Sun home page

How to Write Doc Comments for the Javadoc Tool

http://java.sun.com/j2se/javadoc/writingdoccomments/

But it's in English.

@author Dfeixtay

@version 0.10 2010-10-04

1 note The format of the document note that the document will be used to generate HTML-formatted code reports, so the comment document must be written before the class, domain, constructor, method, definition. A note document consists of two parts-a description, a block tag.

For example:

/**

* The Doget method of the servlet.


* This method was called when a form had its tag value method equals to get.

*

* @param request

* The request send by the client to the server

* @param response

* The response send by the server to the client

* @throws servletexception

* If an error occurred

* @throws IOException

* If an error occurred

*/

public void doget (HttpServletRequest request, httpservletresponse response)

Throws Servletexception, IOException {

DoPost (request, response);

}

The first two behaviors are described, and after the description is finished, the @ sign begins with the block tag annotation.

2 Types of annotations
2.1 File Header Comments
The file header comment starts with/* and ends with */and needs to indicate the file creation time, file name, and namespace information.

For example:

/*

* Created on 2005-7-2

* /

2.2 Class, interface annotations
The annotations for classes and interfaces take the/**. */, which describes the function or related information used to write the class, and the block Mark section must indicate the author and version.

For example:

/**title:xxxx DRIVER 3.0
*description:xxxx DRIVER 3.0
*copyright:copyright (c) 2003
*company:xxxx Ltd.
*
* @author Java Development Group
* @version 3.0
*/

For example:

/**
* A class representing a window on the screen.
* For example:
*
* Window win = new window (parent);
* Win.show ();
*
*
* @author Sami Shaio
* @version%I%,%g%
* @see Java.awt.BaseWindow
* @see Java.awt.Button
*/

Class Window extends Basewindow {

...

}

2.3 Constructor Comments
The constructor comment takes the/** ... */, the description section indicates the function of the constructor, not necessarily the block tag part.

For example:

/**

* Default constructor

*/

There are for example:

/**

* with parameter constructors, initialize schema name, name and data source type

*

* @param schema

* REF Mode Name

* @param name

* Ref Name

* @param type

* ByVal Data Source Type

*/

2.4 Domain annotations
A field note can appear in a comment document, or it can be in a comment document. With/** ... * * The domain comment will be considered as a comment document and appear in the resulting HTML report, while the comment using/* will be ignored.

For example:

/* Due to triger and table with a dmsource, so to distinguish and table the migration success Tag */

Boolean istrigersuccess = false;

Another example:

/** due to triger and table with a dmsource, so to distinguish and table the migration success Tag */

Boolean istrigersuccess = false;

Again for example:

/**

* The x-coordinate of the component.

*

* @see #getLocation ()

*/

int x = 1263732;

2.5 Method Comments
The method note uses the/** ... * *, describes the function of the method, the Block Mark section indicates the method parameters, return value, exception and other information. For example:

/**

* Set whether there is an external code constraint

*

* @param Conn

* Connection connection to the database

*/

2.6 Defining annotations
Rule same field comment.

3 Comment Block Markers
3.1 Order of the marks
The block markers will be in the following order:

...

*

* @param (classes, interfaces, methods and constructors only)

* @return (Methods only)

* @exception (@throws is a synonym added in Javadoc 1.2)

* @author (classes and interfaces only, required)

* @version (classes and interfaces only, required. See footnote 1)

* @see

* @since

* @serial (or @serialField or @serialData)

* @deprecated (see how and if to deprecate APIs)

* ...

A block tag can be repeated as many times as necessary, and multiple occurrences of the tag are in the following order:

@author in chronological order (chronological)

@param by parameter Definition Order (declaration)

@throws in alphabetical order by exception name (alphabetically)

@see in the following order:

@see #field

@see #Constructor (type, type ...)

@see #Constructor (type ID, type ID ...)

@see #method (type, type,...)

@see #method (type ID, type, id ...)

@see Class

@see Class#field

@see class#constructor (type, type ...)

@see class#constructor (type ID, type ID)

@see Class#method (type, type,...)

@see Class#method (type ID, type ID,...)

@see package. Class

@see package. Class#field

@see package. Class#constructor (type, type ...)

@see package. Class#constructor (type ID, type ID)

@see package. Class#method (type, type,...)

@see package. Class#method (type ID, type, id)

@see Package

3.2 Tag Introduction
3.2.1 @param Mark
@param the trailing space followed by the argument's variable name (not the type), followed by a description of the argument to the space.

The first name in the description is the data type of the variable, and the position of the data type can be preceded by a title such as A,an,the. If the parameter is of type int, you do not need to indicate the data type. For example:

...

* @param ch The char used to ...

* @param _image The image is used to ...

* @param _num a number ...

...

For a description of the parameter if it is just a phrase, it is best not to capitalize the initial letter and end it.

The description of the parameter is a sentence, it is best not to capitalize the first letter, if there is a period this means that your description more than a sentence. If you want to capitalize the first letter, you must end the sentence with a period. (Full period in English)

Add ByRef and ByVal two tags inside the company, for example:

* @param _image the image ByRef used to ...

Note that the parameter is a reference pass (pointer), ByVal can be omitted, indicating that the value is passed.

3.2.2 @return Mark
Returns a constructor or function that is empty (void), @return can be omitted.

If the return value is an input parameter, you must use the same descriptive information as the @param of the input parameter.

When necessary, specify the return value of the special condition write.

3.2.3 @throws Mark
@throws used to be @exception.

The contents of the @throws must be defined in the throws part of the function.

3.2.4 @author Mark
The class comment tag.

Function comments can not appear @author.

3.2.5 @version
The class comment tag.

Function comments can not appear @version

3.2.6 @since
The class comment tag.

Indicates which version of the JDK the class can run

For example:

@since JDK1.2

3.2.7 @deprecated
A method of being declared obsolete for some reason.

/**

* @deprecated as of JDK 1.1, replaced by

* SetBounds

* @see #setBounds (int,int,int,int)

*/

3.2.8 @link Mark
Syntax: {@link package.class#member label}

Label is the linked text.

Package.class#member will be automatically converted to the URL of the member file exponentially to Package.class.

4 Use of HTML code
You can use HTML code in the comment Description section.

Represents a paragraph

Indicates automatic labeling

5 Example of annotations
/**

* Graphics is the abstract base class for all Graphics contexts

* Which allow a application to draw onto. Realized on

* Various devices or onto off-screen images.

* A Graphics Object encapsulates the state information needed

* For the various rendering operations that Java supports. This

* State information includes:

*

*

*

*

*

*

*

*

* (see SETXORMODE)

*

*

* Coordinates is infinitely thin and lie between the pixels of the

* output device.

* Operations which draw the outline of a figure operate by traversing

* Along the infinitely thin path with a pixel-sized pen that hangs

* Down and to the right of the anchor point on the path.

* Operations which fill a figure operate by filling the interior

* of the infinitely thin path.

* Operations which render horizontal text render the ascending

* portion of the characters entirely above the baseline coordinate.

*

* Some important points to consider is that drawing a figure that

* Covers a given rectangle would occupy one extra row of pixels on

* The right and bottom edges compared-filling a figure that's

* Bounded by that same rectangle.

* Also, drawing a horizontal line along the same Y coordinate as

* The baseline of a line of text would draw the line entirely below

* The text except for any descenders.

* Both of these properties is due to the pen hanging down and to

* The right from the path the IT traverses.

*

* All coordinates which appear as arguments to the methods of this

* Graphics object is considered relative to the translation origin

* of this Graphics object prior to the invocation of the method.

* All rendering operations modify only pixels which lie within the

* Area bounded by both the current clip of the graphics context

* and the extents of the Component used to create the Graphics object.

*

* @author Sami Shaio

* @author Arthur van Hoff

* @version%I%,%g%

* @since 1.0

*/

Public abstract class Graphics {

/**

* Draws as much of the specified image as is currently available

* With it northwest corner at the specified coordinate (x, y).

* This method would return immediately in all cases, even if the

* Entire image has not yet been scaled, dithered and converted

* For the current output device.

*

* If The current output representation are not yet complete then

* The method would return false and the indicated

* {@link ImageObserver} object would be notified as the

* Conversion process progresses.

*

* @param img The image to be drawn

* @param x The x-coordinate of the northwest corner

* of the destination rectangle in pixels

* @param y the y-coordinate of the northwest corner

* of the destination rectangle in pixels

* @param observer the image observer to being notified as more

* of the image is converted. May is

* NULL

* @return True if the image is completely

* Loaded and was painted successfully;

* False otherwise.

* @see Image

* @see ImageObserver

* @since 1.0

*/

Public abstract Boolean DrawImage (Image img, int x, int y,

ImageObserver observer);

/**

* Dispose of the system resources used by this graphics context.

* The Graphics context cannot is used after being disposed of.

* While the finalization process of the garbage collector would

* Also dispose of the same system resources, due to the number

* of Graphics objects that can is created in short time frames

* It's preferable to manually free the associated resources

* Using this method rather than to rely on a finalization

* Process which happen for a long period of time.

*

* Graphics objects which is provided as arguments to the paint

* and update methods of components is automatically disposed

* By the system when those methods return. Programmers should,

* For efficiency, call the Dispose method when finished using

* A Graphics object only if it is created directly from a

* Component or another Graphics object.

*

* @see #create (int, int, int, int)

* @see #finalize ()

* @see Component#getgraphics ()

* @see Component#paint (Graphics)

* @see Component#update (Graphics)

* @since 1.0

*/

public abstract void Dispose ();

/**

* Disposes of this graphics context once it is no longer

* referenced.

*

* @see #dispose ()

* @since 1.0

*/

public void Finalize () {

Dispose ();

}

}





Some compilation environments, such as BlueJ, can perform Javadoc automatically. You can also invoke the Javadoc using the following command in the command shell:
Javadoc Myclass.java

Where Myclass.java is the name of the user-created class. Or, if you want to create comments for several Java files, use Javadoc *.javajavadoc

The utility generates HTML-formatted files, such as myclass.html. You can view this document in a browser.
If you need to familiarize yourself with HTML, you can embed HTML tags in comments to determine fonts or add images. But perhaps most importantly, Javadoc automatically provides hyperlinks to other classes and methods.

Java Document Comment writing format