Creating Javadoc annotations consists of Javadoc tags and descriptive text, you can add annotations to classes, interfaces, or elements in classes such as constructors, ranges, methods, and so on. Let's take a look at a program with Javadoc annotation, whose code looks like this:
Code Listing 1 Person.java
1. Package Javadoc;
2. Import java.io.Serializable;
3./**
4. * <pre> Description object, with two attributes, respectively, name and gender. </pre>
5. * @see Javadoc.tool.Car
6. * @version 1.0, 2005-04-12
7. * @author Chen Xionghua
8. * @since JDK1.3
9. * /
public class person implements Serializable
11. {
12./** male, the value is {@value}*/
public static final int MALE = 1;
14./** Female, the value is {@value}*/
public static final int FEMALE = 2;
16./** Name * *
protected String name;
18./** Age * *
protected int sex;
20./**
21. * Construct a person instance. Set the name and sex of person.
22. *
* @param name String
* @param sex int sex, valid value is {@link #MALE male} and {@link #FEMALE}
* @throws personargumentexception
* @see javadoc.tool.car#drive (int)
-* *
Public person (String name, int sex) throws Personargumentexception
29. {
if (sex!= MALE && sex!= FEMALE)
throw new Personargumentexception ("Incorrect parameters");
THIS.name = name;
This.sex = sex;
34.}
35./**
36. * Access to gender codes.
* @return int
@see MALE
* @see FEMALE
-* /
public int Getsex ()
42. {
Sex return;
44.}
45./**
46. * Setting Gender
* @param sex int
* *.
The public void setsex (int sex)
50. {
This.sex = sex;
52.}
53.}
All Javadoc annotations start with/** and end with a * *, each containing some descriptive text and several Javadoc tags. Descriptive text can be used not only in flat text, but also in HTML text, and Javadoc tags are generally prefixed with "@" and some are prefixed with "{@", ending with "}", such as {@value}.
Line 3rd to 9th is a comment for the class that is positioned before the class definition line of code, where the <pre></pre> label in line 3rd is an HTML tag, and the row 4th to 7th is the Javadoc label, which is mapped to the display style in the Javadoc document as shown in the following illustration:
Figure 4 Class annotations
Lines 12th and 14 are comments of constants that precede the constant definition line of code, {@value} represents the output of the constant value to the Javadoc document, and 16th, 18 is a comment for the member variable. Member constants and variables are collectively referred to as domain values, which are displayed together:
Figure 5 member constant/variable annotation summary
In addition to the annotation summary, each member range has its own separate detailed comment.
The 20th to 27th is the annotation of the class constructor, which has two descriptive messages, the first of which is "construct a person instance." The second sentence is to set the name and sex of the person. , only the first sentence description is displayed in the summary list of the constructor, using the. "Separates the descriptive information from each sentence. In the detailed description section of the constructor, all the descriptive information is displayed. This principle is also appropriate for the summary of variables and methods, see the detailed description of the method summary and method in the Javadoc help documentation below, as shown in Figure 26-6, figure 26-7:
Figure 6 Method Summary
Figure 7 Constructor Detailed description
There are more Javadoc tags for the constructor, @param a description of the method entry, @throws a description that throws an exception for the method,< @link > tags provide a URL in the Javadoc document that links to other parts of the document.
35th to 40th, 45~48 is a notation for the method, @return a description of the method return type, as we mentioned earlier, the Javadoc documentation contains a summary list of methods, each corresponding to a detailed description section, such as Getsex (), as follows:
Figure 8 Detailed description of the Getsex () method
By describing this example, we have a general idea of the labeling and writing of Javadoc. Comments are generally placed before the annotation element, such as the annotation of the class before the public class XXX class declaration code, and the comment for the range is in front of public int xxx. In order to write beautiful Javadoc documents, you need not only to master simple HTML writing knowledge, but also to understand the Javadoc label knowledge.
The Javadoc tags supported by different versions of the JDK are not the same, and they can be divided into different types according to where the labels apply, such as the @return tag that applies only to the method, which we call the method label, only for the @serial label of the variable, which we call the range label, and so on. Often a label applies to a variety of places, and the following table describes the commonly used Javadoc tags:
Table 2?1 Javadoc Label description
| 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 |
| Description of @param parameter name |
The parameter name of the method and the descriptive information, such as the entry parameter, can be noted in this note. |
√ |
√ |
constructors, methods |
| @return Description |
Comment on return value of function |
√ |
√ |
Method |
| @deprecated Expired Text |
Identifying with the program version of the upgrade, the current API has expired, only to ensure that compatibility persists, 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 Descriptive text |
What version of the API is developed to support after what program. |
√ |
√ |
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 you annotate a constant, if you want to include its value in the document, the label is used to refer to the value of the constant. |
|
√ (JDK1.4) |
Static domain |
In addition, there are several infrequently used labels for @serial, @serialField, @serialData, {@docRoot}, {@inheritDoc}, {@literal}, {@code} {@value arg}, We expand the narrative and interested readers can view their detailed help information through Http://www.java.sun.com/j2se/javadoc.
Here are some examples of javadoc tags that are not easily understood in the table.
* @see
You can link the current point to a description of a class, range, or method through this tag. In order to link to the domain or method of the current class, a # number must be taken before the range and method name, such as:
@see #getSex ()
@see #MALE
You can also use this tag to link to other classes of methods, the range of the description, assuming we create a project called Javadoc, in this project includes the code Listing 1 Javadoc. Person.java file, now we add a Javadoc.tool.Car class to the project, and the program code looks like this:
1. Package javadoc.tool;
2.
3./**
4. * <pre> Automotive object class. </pre>
5. * @version 1.0, 2005-04-12
6. * @author Chen Xionghua
7. * @since JDK1.3
8. */
9. public class car
10. {
One. Public car ()
12. {
13.}
14./**
15. * Driving a car in a certain direction
* @param direction int method
* @param speed int speed
18. */
public void Drive (int direction,int speed)
20. {
/*do sth*/
22.}
23./**
24. * Driving in front of the car
* @param speed int speed
26. */
public void drive (int speed)
28. {
/*do sth*/
30.}
31.}
If the person class has something to do with the car class, we would like to have a link to the car document that you see in the Javadoc documentation for someone so that the developer can track down the documentation for the associated car class. To do this, you can give a @see label in the comments for the person class.
1./**
2. * <pre> Description object, with two attributes, respectively, name and gender. </pre>
3. * @see Javadoc.tool.Car
4. * @version 1.0, 2005-04-12
5. * @author Chen Xionghua
6. * @since JDK1.3
7. */
Look at the @see label on line 3rd, because the car and person classes are not in the same package, so you must specify the full name of the class, and of course, if Person.java has passed the import Chapter19.tool.Car, the car class is introduced. @see can be used directly with a class name without a package: @see car. So the @see reference annotation in Javadoc is similar to referencing a class in Java code.
A more specific application is to link to overloaded methods from the current document, such as overloaded methods with two drive () in the car, and how to link to different overloaded methods and comments through @see? Because only the method name cannot be positioned, you need to specify the type of the parameter in the method name, as shown in the following example:
• @see javadoc.tool.car#drive (int,int): Link to drive (int direction,int speed).
• @see javadoc.tool.car#drive (int): Link to drive (int speed).
If the annotation is not specified correctly, the @see part of the comment will not appear in the Javadoc document.
* @link
The @see of @link is very similar, except that it can be nested within the descriptive text of the annotation and converted into an associated link when the Javadoc document is generated. @link in the comments of the person's constructor:
1./**
2. * Construct a person instance. Set the name and sex of person.
3. *
4. * @param name String
5. * @param sex int sex, valid value is {@link #MALE} and {@link #FEMALE}
6. * @throws personargumentexception
7. * @see javadoc.tool.car#drive (int)
8. */
The Javadoc label with {} is like a variable that is replaced with a specific value or link when converted to a document.
