Javadoc annotation Detailed __java

Classification of Java annotations

1, single-line annotation: int SUM = 100; This is a single-line comment

2, Multiline comments:

/*

* This is a multiline comment.
*/

3. Documentation Comments:

/**

* This is a document comment

* @return A

*/

Java Annotations and documentation comments

As a Java programmer, we must all like to read the official development documentation, which includes information such as class and interface parameter methods, and so on, as well as the relationships among many classes. Java development documents are displayed by HTML pages, but it took a long time before we realized that these documents were not actually written out at 1.1, and we could build them ourselves.

After the JDK is installed, there is a Src.jar file or Src.zip file under the installation directory, which are compressed in zip format and can be decompressed using WINZIP. After decompression, we can see that the sub directory is full of. java files. Yes, these are the Java running class source code, very complete, even the annotations are written clearly, we can compare the comments here and the development of documents to java.util.List as an example: This is the official website API screenshot

Next look at the source information:

Package java.util;

/**
* An ordered collection (also known as a <i>sequence</i>). The user of this
* Interface has precise control over where in the ' list each element is
* inserted. The user can access elements by their integer index (position in
* the list), and search for elements in the list.<p>
*
* Unlike sets, lists typically allow duplicate. More formally,
* Lists typically allow pairs of elements <tt>e1</tt> and <tt>e2</tt>
* such that <tt>e1.equals (E2) </tt>, and they typically allow
* NULL elements if they allow null elements at all. It is not inconceivable
* That someone might wish to implement a-list that prohibits duplicates by
* Throwing runtime exceptions when the user attempts to insert them, but we
* Expect this usage to be rare.<p>
*
* The <tt>List</tt> interface places additional stipulations, beyond those
* Specified in the <tt>Collection</tt> interface, on the contracts of the
* &LT;TT&GT;ITERATOR&LT;/TT&GT;, <tt>add</tt>, <tt>remove</tt>, <tt>equals</tt ", and
* <tt>hashCode</tt> methods. Declarations for the other inherited methods are
* Also included for convenience.<p>

.....

* @param <E> the type of elements in this list
*
* @author Josh Bloch
* @author Neal Gafter
* @see Collection
* @see Set
* @see ArrayList
* @see LinkedList
* @see Vector
* @see arrays#aslist (object[])
* @see collections#ncopies (int, Object)
* @see Collections#empty_list
* @see Abstractlist
* @see Abstractsequentiallist
* @since 1.2
*/

Public interface List<e> extends collection<e> {

.....

}

It can be seen that the Java development document is actually in the code in accordance with the corresponding rules of the annotation, which is critical to the reader and users of the program, it can be seen that learning to write notes for a programmer is very critical, but also to reflect the level of a programmer. document and document annotation formats

Document annotations can be described in classes, methods, and properties. Be aware of the details inside the document.

The document is generated in HTML, and the format identifier in HTML is not Javadoc, but we write it in the comments, for example, when we need to change lines, instead of typing a line break, but writing a <br> if you want to segment, you need to use the <p>

As a result, formatting a document means adding an HTML-appropriate label to the comment.

The body of the document comment is not copied directly to the output file (the document's HTML file), but rather reads each row, deletes the leading * and * number before the space, and then enters the document. Such as:
/**
* This is the.

* This is second line.

This is third line.
*/

The HTML source code after compiling the output is:
This is the.

This is second line.

This is third line.

* Note that the document description needs to follow the three components of a class, interface, method, or property document comment

The first section is a brief description of classes, interfaces, methods, and properties. Briefly at the top of the document annotation, the end of the summary needs to be preceded by a point number ".", which is to use the point number to split the document annotation, sometimes the point number will be wrong, we will use <p> as the beginning of the second part of the split.

The second part is the detailed part of the annotation, the attribute or the method and so on detailed explanation, in the format does not have any special request.

The third part is the special Description section, which includes the declaration author, the version description, the parameter description, the reference description, the return value description. Throw exception description, this part of the best and the second part of a blank line, or there may be an error.

commonly used Javadoc tags and their use

1, the use of @see:

There are three kinds of syntax in @see

①, @see class name

The class name can only write out the class name, such as String, or write the full name as needed: java.lang.String, but note that you need to import this class in the Java source file when you use the class name, otherwise you can use the full name only.

②, @see # Method name or property name

If it is a property name, you only need to write out the property name, and if it is a method name, you need to write out the method name and the parameter type, and if there are no arguments, write a pair of parentheses.

such as: @see #contains (Object), @see #count (), @see number

③, @see class name # Method name or property name

such as: @see Object#equals (Object), @see java.lang.string#tostring ()

2, @author, the use of @version:

The two tags indicate the author and version number, and Javadoc automatically ignores it by default, but command-line switches-author and-version can modify the functionality to include the flow of information, both of which can be used multiple, but the version number is only valid for the first occurrence.

3, the use of @param, @return and @exception:

These three tags can only be used for methods, @param describe parameters, @return describe the return value, @exception the description throws an exception, and use the following:

Description of parameters of ①, @param parameter names

Each @param can only describe the parameters of a single method, and may be used more than once.

②, @return return value description

A method can only use one @return, and if there are multiple, Javadoc warns, and only the first declaration is valid.

@exception Exception class Name exception description

@exception can be used more than once, and the class name of the exception needs to be aware of whether there is an import in the Java original file, and if there is no need to write the class name.

Such as:

/**
* A brief description of the test method, which is used for Javadoc testing.
* <p> test method Detailed description, here is the first line of detailed description <br>
* The second line of the detailed description of the test method
*
* @param a Firstnum
* @param b Lastnum
* @exception Java.lang.ArithmeticException throw when B is 0
* @return return value is a/b
*/
public int test (int a,int b) throws java.lang.arithmeticexception{
return a/b;
}

* Note: When writing documentation comments should pay attention to the correct matching parameters, Javadoc to some extent will not check our written documentation comments, if write errors may cause some confusion
Javadoc Command

usage: Javadoc [options] [packagenames] [SourceFiles]

Options:

-public only show public classes and members
-protected display Protected/public classes and members (default)
-package display Package/protected/public classes and members
-private Show all classes and members
-D destination directory for output files
-version contains @version segments
-author contains @author segments
-splitindex the index into each letter to a file
-windowtitle document's browser window title

Javadoc can be compiled for a given package list, such as: Javadoc XCG xcg.test

You can also give a list of source files, such as Javadoc Xcg/test/javadoctest.java

The results of these two methods are different, and the document generated by the package list is divided into three parts: Package list, class list, and class description

You can use File->export->javadoc in eclipse or myeclipse to manually output Javadoc, and you need to be aware that errors can occur when you build: an unmapped character encoded GBK, At this point you need to add a sentence control character to the final step of the process:-encoding UTF-8-charset UTF-8, such as:

Annotation Specification

1, the principle of annotation:

① annotation Form Unification

② annotation content is accurate and simple

2, the annotation condition:

① Basic annotation (must be added): Class, annotation of interface, comment of constructor, comment of method, annotation of global variable, comment of Field/property

② Special must add comments: Typical algorithms, code is not clear when the annotation, modify the code need to annotate, in the Loop branch need to annotate, provide other information such as the interface must be commented.