Javadoc annotation specification and javadoc Annotation

Javadoc annotation specification and javadoc Annotation

Javadoc comments
1. Java documentation

// Comment a row
/* ...... */Annotate several rows
/**... */Annotate several lines and write them into the javadoc document.

The multiple lines of such annotation are usually written as follows:

/**
*.........
*.........
*/

Javadoc-d file storage directory-author-version source file name. java
This command compiles a file named "source file name. java, and store the generated documents under the directory specified by "document storage directory". In the generated documents, index.html is the homepage of the document. -Author and-version options can be omitted.

Ii. Document comment format

1. format document and document comments

The generated documents are in HTML format, and the identifiers in HTML format are not added by javadoc, but written when writing comments.
For example, if you want to change the row, you do not need to input a carriage return, but write <br>. If you want to segment, you should write <p> before the segment.
The body of the document comment is not directly copied to the output file (the HTML file of the document), but read each line and delete leading * signs and spaces before * signs, enter the document. For example

/**
* This is first line. <br>
* *** This is second line. <br>
This is third line.
*/


2. Three parts of the document comment
Example:

/**
* Brief description of the show method.
* <P> detailed description of the show method first line <br>
* The second line of the show method is described in detail.
* @ Param B true indicates display, and false indicates hidden.
* @ Return no return value
*/
Public void show (boolean B ){
Frame. show (B );
}

The first part is a brief description. In this document, there is a list of attributes and methods first, and then detailed descriptions are provided one by one.
The description is written at the beginning of a document comment, before the first vertex ). In other words, it is to use the first vertex to separate the comments of the document. It is a brief description, followed by the second part and the third part.

The second part is the detailed description. This section describes the attributes or methods in detail. There are no special requirements on the format. It can contain several periods.
* Brief description of the show method.
* <P> detailed description of the show method first line <br>
* The second line of the show method is described in detail.

The description is also included. Remember this.

The third part is the special description section. This part includes version description, parameter description, and return value description.
* @ Param B true indicates display, and false indicates hidden.
* @ Return no return value

3. Mark with javadoc
The javadoc tag consists of the "@" and its subsequent tag types and special annotation references.
The javadoc labels are as follows:
@ Author indicates the author of The development class module
@ Version indicates the version of the module.
@ See references, that is, related topics
@ Param description of a parameter in the other method
@ Return description of the return value of the Method
@ Exception describes possible exceptions thrown by methods.

@ Author name
@ Version
@ Author can be used multiple times to specify multiple authors. Each author in the generated document is separated by a comma. @ Version can also be used multiple times, only valid for the first time

Use @ param, @ return, and @ exception to describe the method
These three tags are only used for methods. @ Param describes the parameters of the method, @ return describes the return value of the method, and @ exception describes the exceptions that may be thrown by the method. Their syntax is as follows:
@ Param parameter name parameter description
@ Return value description
@ Exception Class Name Description


4. javadoc command
Usage:
Javadoc [options] [packagenames] [sourcefiles]

Option:

-Public: Only public classes and members are displayed.
-Protected: displays the protected/public class and members (default)
-Package: displays package/protected/public class and members.
-Private: displays all classes and members.
-D <directory> target directory of the output file
-Version contains @ version segments
-Author contains @ author segments
-Splitindex divides the index into one file corresponding to each letter.
-Windowtitle <text> the browser window title of the document

You can specify a package list or a list of source program files when compiling a document using javadoc. For example, there are two classes in CLASSPATH:

Fancy. Editor
Fancy. Test
Fancy. editor. ECommand
Fancy. editor. EDocument
Fancy. editor. EView

You can directly compile the class:
Javadoc fancy \ Test. java fancy \ Editor. java fancy \ editor \ ECommand. java fancy \ editor \ EDocument. java fancy \ editor \ EView. java

The package name can also be used as the compilation parameter, for example, javadoc fancy. editor.
Let's take a look at the differences between the two methods.

So far, javadoc has been briefly introduced. To use it well, you need to use it more. For more information, see the standard java code.
Java code specification
-- Comment

@ Author LEI

@ Version 1.10
1. Document Format

The annotation document is used to generate code reports in HTML format. Therefore, the annotation document must be written before classes, domains, constructors, methods, and definitions. The annotation document consists of two parts: Description and block tag.

For example:

/**

* The doGet method of the servlet.

* This method is called when a form has 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 actions are described. After the description is completed, the @ symbol starts and marks the block as the marker.
2 annotation types
2.1 File Header comments

The file header comment starts with/* and ends with */. You must specify the file creation time, file name, and namespace information.

For example:

/*

* Created on 2005-7-2

*/
2.2 class and interface comments

Class and interface Annotations /**... */, The description is used to write the role or related information of the class, and the block tag must contain the author and version.

For example:

/** Title: xxxx driver 3.0
* Description: xxxx driver 3.0
* Copyright: Copyright (c) 2003
* Company: XXXX Co., 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

Constructor comments using /**... */. The description part indicates the role of the constructor. It may not have block tags.

For example:

/**

* Default constructor

*/

For example:

/**

* Constructor with parameters, initialization mode name, name, and Data Source Type

*

* @ Param schema

* Ref mode name

* @ Param name

* Ref name

* @ Param type

* ByVal Data Source Type

*/
2.4 domain Annotation

Domain comments can appear in the comments or not in the comments. Use /**... */Domain annotation will be considered as a hot comment document appearing in the final HTML report, And /*... */Comments are ignored.

For example:

/* Because the triger and table use a DMSource, it is necessary to distinguish it from the table's migration success mark */

Boolean isTrigerSuccess = false;

For example:

/** Because the triger and table use a DMSource, you must mark the success of table migration */

Boolean isTrigerSuccess = false;

For example:

/**

* The X-coordinate of the component.

*

* @ See # getLocation ()

*/

Int x = 1263732;

2.5 method comments

Method annotation using /**... */, The description part indicates the function of the method, the block tag part indicates the parameters, return values, exceptions, and other information of the method. For example:

/**

* Set whether external code constraints exist.

*

* @ Param conn

* Connection to the database

*/
2.6 define comments

The rule is annotated with the same domain.
3. Comment block tags
3.1 mark order

The block tag is 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 When To Deprecate APIs)

*...

A block tag can be repeated multiple times as needed. Multiple tags appear in the following order:

@ Author: chronological)

@ Param: declaration)

@ Throws follow the alphabetic order of the Exception name (alphabetically)

@ See:

@ 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 mark Introduction
3.2.1 @ param flag

@ Param is followed by a space and the variable name (not a type) of the parameter. The space is followed by the description of the parameter.

In the description, the first data type named this variable indicates that there can be a title before the ranking of the data type, such as a, an,. If it is an int type parameter, you do not need to specify the data type. For example:

...

* @ Param ch the char is used ......

* @ Param _ image the image is used ......

* @ Param _ num: a number ......

...

If the parameter description is just a phrase, it is best not to use uppercase letters or end with periods.

The parameter description is a sentence. It is better not to use uppercase letters. If a full stop occurs, it means that there are more than one sentence to describe. If you have to use uppercase letters, you must use periods to end the sentence. (English end)

Add ByRef and ByVal labels inside the company, for example:

* @ Param _ image the image ByRef is used ......

This parameter indicates that it is a reference transfer (pointer). ByVal can be omitted, indicating that it is a value transfer.
3.2.2 @ return flag

Returns a void constructor or function. @ return can be omitted.

If the returned value is an input parameter, the description must be the same as the input parameter @ param.

If necessary, specify the return value for special conditions.
3.2.3 @ throws flag

@ Throws previously used @ exception.

@ Throws content must be defined in the throws part of the function.
3.2.4 @ author flag

Class annotation tag.

@ Author is not allowed in the function comment.
3.2.5 @ version

Class annotation tag.

@ Version does not appear in function comments.
3.2.6 @ since

Class annotation tag.

Indicates the JDK version that the class can run.

For example:

@ Since JDK1.2
3.2.7 @ deprecated

The method for declaring to be deprecated for some reason.

/**

* @ Deprecated As of JDK 1.1, replaced

* SetBounds

* @ See # setBounds (int, int)

*/
3.2.8 @ link tag

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

Label is the link text.

Package. class # member is automatically converted to the URL of the member file pointing to package. class.
4. Use of HTML code

You can use HTML code in the annotation description section.

...
Paragraph

*....

Indicates automatic label
5 annotation example

/**

* Graphics is the abstract base class for all graphics contexts

* Which allow an application to draw onto components 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 providers des:

*

# * The Component to draw on

# * A translation origin for rendering and clipping coordinates

# * The current clip

# * The current color

# * The current font

# * The current logical pixel operation function (XOR or Paint)

# * The current XOR alternation color

* (See setXORMode)

*

*

* Coordinates are infinitely thin and lie between the pixels of

* 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 abve the baseline coordinate.

*

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

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

* The right and bottom edges compared to filling a figure that is

* Bounded by that same rectangle.

* Also, drawing a horizontal line along the same y coordinate

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

* The text should t for any descenders.

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

* The right from the path that it traverses.

*

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

* Graphics object are 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

* 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 its northwest corner at the specified coordinate (x, y ).

* This method will return immediately in all cases, even if

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

* For the current output device.

*

* If the current output representation is not yet complete then

* The method will return false and the indicated

* {@ Link ImageObserver} object will be notified as

* 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 be notified as more

* Of the image is converted. May be

* 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 be used after being disposed.

* While the finalization process of the garbage collector will

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

* Of Graphics objects that can be created in short time frames

* It is preferable to manually free the associated resources

* Using this method rather than to rely on a finalization

* Process which may not happen for a long period of time.

*

* Graphics objects which are provided as arguments to the paint

* And update methods of Components are automatically disposed

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

* For efficiency, call the dispose method when finished using

* A Graphics object only if it was created directly from

* Component or another Graphics object.

*

* @ See # create (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 ();

}

}

 

Reprinted from http://kelaocai.iteye.com/blog/227822