Javadoc is a technology provided by sun, which extracts classes, methods, members, and other annotations from the program source code to form an API help document supporting the source code. The Javadoc command is used to generate your own API documentation, using: In DOS, enter the Javadoc + file name in the directory where the target file is located. java.
| Label |
Description |
JDK 1.1 Doclet |
Standard Doclet |
Label type |
| @author author |
Author identification |
√ |
√ |
Packages, classes, interfaces |
| @version version number |
Version number |
√ |
√ |
Packages, classes, interfaces |
| @param parameter Name Description |
The parameter name and description information of the method, such as the special requirements for the entry, can be commented on here. |
√ |
√ |
constructors, methods |
| @return Description |
Comment on the return value of the function |
√ |
√ |
Method |
| @deprecated Expired Text |
Logo as the program version of the upgrade, the current API has expired, only to ensure that the compatibility still exists, so that developers should not use this API. |
√ |
√ |
Package, class, interface, domain, constructor, method |
| @throws Exception class name |
The exception that is thrown by the constructor or method. |
|
√ |
constructors, methods |
| @exception Exception class name |
With @throws. |
√ |
√ |
constructors, methods |
| @see References |
View related content, such as classes, methods, variables, and so on. |
√ |
√ |
Package, class, interface, domain, constructor, method |
| @since Description Text |
The API is developed after what version of the program is supported. |
√ |
√ |
Package, class, interface, domain, constructor, method |
| {@link package. Class # member Label} |
Link to a document that corresponds to a specific member. |
|
√ |
Package, class, interface, domain, constructor, method |
| {@value} |
When commenting on a constant, if you want to include its value in the document, the value of the constant is referenced by the label. |
|
√ (JDK1.4) |
Static domain |
There are also several infrequently used tags for @serial, @serialField, @serialData, {@docRoot}, {@inheritDoc}, {@literal}, {@code} {@value arg}, as infrequently used. We unfold the narrative and interested readers can view the help documentation. Javadoc Make notes
A. Java documentation
Comment Line
*/* ... * * Comment several lines
/** ... * * Comment several lines and write to Javadoc document
Usually the multiline notation of this comment is as follows:
/**
* .........
* .........
*/
javadoc-d Document storage directory-author-version source file name. java
This command compiles a Java source file named "source file name. Java" and stores the resulting document in the directory specified in the "document Directory" where the index.html is the first page of the document. -author and-version two options can be omitted.
Two. Format of document annotations
1. Formatting of document and document annotations
The generated documents are in HTML format, and these HTML format identifiers are not Javadoc, but we write them when we write the comments.
For example, instead of typing in a carriage return, you need to change the line, but write <br>, and if you want to segment, write <p> before the paragraph.
The body of the document comment is not copied directly to the output file (the document's HTML file), but after each line is read, the leading * number and the previous space of the * number are deleted and then entered into the document. Such as
/**
* This was first line. <br>
This was second line. <br>
This was third line.
*/
2. Three parts of the documentation note
First examples are as follows
/**
* A brief description of the show method.
* Detailed description of the <p>show method first line <br>
* Detailed description of the Show method the second line
* @param b True indicates display, false means hidden
* @return No return value
*/
public void Show (Boolean b) {
Frame.show (b);
}
The first part is a brief description. Document, for the properties and methods are all preceded by a list, followed by a detailed description of one
A brief description is written before the first dot (.) in a document comment, including the point number. In other words, the document comments are separated by the first dot, preceded by a brief description, followed by the second and third parts.
The second part is the detailed description section. This section describes the properties or methods in detail, there are no special requirements in the format, and can contain several dot numbers.
* A brief description of the show method.
* Detailed description of the <p>show method first line <br>
* Detailed description of the Show method the second line
A brief description is also therein. That's a point to remember.
The third part is the Special Description section. This section includes release notes, parameter descriptions, return value descriptions, and so on.
* @param b True indicates display, false means hidden
* @return No return value
Three. Using the Javadoc tag
The Javadoc tag consists of the tag type and the private comment reference followed by "@".
The Javadoc tags have the following:
@author identify the author of the development of such modules
@version indicate the version of the module
@see reference steering, i.e. related topics
@param a description of a parameter in the method
@return Description of the return value of the method
@exception description of the exceptions that the method might throw
@author Author name
@version version number
Where @author can be used multiple times to indicate multiple authors, separated by commas (,) between each author in the resulting document. @version can also be used multiple times, only for the first time valid
Instructions for using @param, @return, and @exception
These three tokens are used only for methods. @param describes the parameters of the method, @return describes the return value of the method, @exception describes the exception that the method might throw. Their syntax is as follows:
Parameter description of the @param argument name
@return Return Value Description
@exception Exception class name description
Four. Javadoc command
Usage:
Javadoc [Options] [packagenames] [SourceFiles]
Options:
-public Show only public classes and members
-protected display Protected/public classes and members (default)
-package displaying package/protected/public classes and members
-private Show all classes and members
-D <directory> destination directory for output files
-version contains @version segments
-author contains @author segments
-splitindex divides the index into one file per letter
-windowtitle <text> Document browser window title
Javadoc can be given a list of packages when compiling a document, or a list of source program files. For example, under CLASSPATH there are two packages of several classes as follows:
Fancy. Editor
Fancy. Test
Fancy.editor.ECommand
Fancy.editor.EDocument
Fancy.editor.EView
You can compile the class directly:
Javadoc Fancy\test.java Fancy\editor.java Fancy\editor\ecommand.java Fancy\editor\edocument.java fancy\editor\ Eview.java
It is also possible to give a package masterpiece as a compile parameter, such as: Javadoc Fancy Fancy.editor
You can see the difference between the two methods.
So far Javadoc simply introduced, want to use her or to use more, more reference standard Java code
Java Code Specification
--Notes
@author LEI
@version 1.10 2005-09-01
1 formatting of the note document
Note 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 gaze.
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 hot in the final generated HTML report, and use/* ... * * comments 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:
*
# * 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 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 ();
}
}
Javadoc and Javadoc Annotation specifications
