A brief discussion on the role of @param annotation and @see annotation in Java-javaTutorial-php.cn

A brief discussion on the role of @param annotation and @see annotation in Java

高洛峰

Release： 2017-01-23 15:23:59

Original

1940 people have browsed it

@ param
@ The param tag can archive a single parameter of a method or constructor, or type parameters of a class, interface, or generic method. When using the @param tag, we should use one for each parameter of the method. The first word of each paragraph will be treated as the parameter name, and the remaining parts will be treated as its description:

@param max The maximum number of words to read.

Copy after login

When archiving type parameters, we Type parameter names should be preceded by < and >:

@param一e element type of this List

Copy after login

However, type parameters usually do not require explicit documentation because their meaning is obvious.

@ see
@ The see tag can create cross-references that link to other javadoc documents. We can name any identifier after this tag, although we must fully qualify them. For example, you can usually name a class member by its simple name, but if the member is an overloaded method, you must specify the overloaded version of the method by enumerating the types of each parameter. We can use unqualified names to specify interfaces or classes in the current package, but we must use fully qualified names to specify types in other packages. We can specify members of a type by using # in front of the member name. The following are all valid @ see tag formats:

@see #getName
 
@see Attr
 
@see com.magic.attr.Attr
 
@see com.magic.attr.Deck#DECK-SIZE
 
@see com.magic.attr.Attr#getName
 
@see com.magic.attr.Attr#Attr(String)
 
@see com.magic.attr.Attr#Attr(String，Object)
 
@see com.magic.attr
 
@see Attribute Specification
 
@see "The Java Developer&#39;s Almanac"

Copy after login

The first form refers to the method named getName, which is located with the documentation comment itself This syntax can also be applied to constructors and fields within the same class or interface, or within a surrounding class or interface. The second form refers to a class in the current package or a class in an imported package. The third form refers to a class using its fully qualified name.

The last four forms of @see refer to members, of which the first two are about the domain (DECK-SIZ) and the method (getName). We can use the method name directly, because in the Attr class Only one getName method is defined in. The latter two forms refer to the constructor of the Attr class. One constructor accepts a string argument, while the other constructor accepts a string and an object. Or when a method has an overloaded version, we must specify the argument of the overloaded version we want to reference.

The following @see form directs the reader to a specific package: com.magic.attro#.

## The last two forms allow us to reference other documents. The former uses to define links, and the latter uses quotation marks to enclose the document name. We can use these two forms to direct readers to it. Other documents, such as complete instructions.

The @see form of naming a language entity (all forms except the last two forms above) can be followed by a label. In the generated document, the name of this label will replace the name of the entity. For example:

@ see #getNameAttribute Names

Copy after login

## will create a link to the getName document, but it will The text shown is "Attribute Names" instead of "getName". Normally we should use the real name of the member, but the features shown here can occasionally be useful.

More tips on @param in Java. For articles related to the role of annotations and @see annotations, please pay attention to the PHP Chinese website