Java experience: writing methods of class annotation documents

Source: csdn Author: chensheng913

One of the most considerate designs for the Java language is that it is not intended to allow people to write programs in order to write programs-people also need to consider the docalization of programs. The biggest problem with docalization of programs is the maintenance of documents. If the document is separated from the code, the document will be changed every time the Code is changed, which will undoubtedly become quite troublesome.

The solution seems simple: link the Code with the document. To achieve this, the simplest way is to place all content in the same file. However, to make everything uniform, a special annotation syntax must also be used to mark special documents; a tool is also required to extract these annotations, and display it in a valuable form. These are all required by Java.

The tool used to extract comments is called javadoc. It uses some Java compiler technology to find the special annotation mark of the program we place. It not only extracts information indicated by these tags, but also extracts the class name or method name adjacent to the annotation. In this way, we can use the lightest workload to generate very professional program documents.

Javadoc outputs an HTML file, which can be viewed in your Web browser. This tool allows us to create and manage a single source file and generate useful documents vividly. With jvadoc, we can use standard methods to create documents. In addition, it is very convenient, so we can easily obtain the documentation of all Java libraries.

2. Specific syntax

All javadoc commands can only appear in the "/**" comment. But as usual, the Comment ends with a "*/". Javadoc is mainly used in two ways: embedded HTML, or "document tag ". Here, "document tag" (Doc
Tags) are some commands starting with "@" and placed at the beginning of the comment line (but the leading "*" will be ignored ).
There are three types of annotation documents that correspond to the elements behind the annotation: Class, variable, or method. That is to say, a class annotation is located before a class definition; a variable annotation is located before the variable definition; and a method definition is located before a method definition. As shown in the following simple example:

/** A class comment */ Public class docTest { /** A variable comment */ Public int I; /** A method annotation */ Public void f (){} }

Note that javadoc can only process comments for public and protected members. Comments of "private" and "friendly" members (see chapter 5) are ignored, and we cannot see any output (you can also use-private to mark including private members ). This makes sense, because only public and protected members can be used outside the file, which is the hope of the client programmers. However, all class annotations are included in the output results.

The output of the above Code is an HTML file, which has the same standard format as other Java documents. Therefore, users will be very familiar with this format and can easily "Roam" in the classes you designed ". When designing a program, be sure to enter the above Code and use javadoc to process it and view the final effect of the HTML file.

3 embed HTML
Javadoc passes the HTML command to the final HTML document. This allows us to take full advantage of the huge power of HTML. Of course, our final motivation is to format the code, not to be favored. The following is an example:

/** * * System. out. println (new Date ()); * */ HTML can also be used in other Web documents to format common text to make it more organized and beautiful: /** * You can even insert a list: * * Project 1 * Project 2 * Project 3 * */

Note that in the document comment, the asterisks at the beginning of a line are discarded by javadoc. Leading spaces are also discarded. Javadoc will format all the content to make it consistent with the standard document appearance. Do not set

Or

This title is used as embedded HTML, because javadoc inserts its own title, and the title we give will conflict with it.
All types of annotation documents-classes, variables, and methods-support embedding HTML.

4 @ see: reference other classes
All three types of annotation documents can contain the @ see Mark, which allows us to reference documents in other classes. For this tag, javadoc generates the corresponding HTML and directly links it to other documents. The format is as follows:

@ See class name
@ See complete Class Name
@ See complete Class Name
Each style automatically adds a hyperlink "See Also" (See) entry to the generated document. Note that javadoc does not check the specified hyperlinks and does not verify whether they are valid.

Category 5 Document tags
Embedded with HTML and @ see references, class documents can also include tags for version information and the author's name. Class documentation can also be used for "interface" purposes (this book will be explained in detail ).

1. @ version
The format is as follows:
@ Version
"Version information" indicates any materials suitable for version description. If the "-version" mark is used in the javadoc command line, the generated HTML document is extracted and published.

2. @ author
The format is as follows:
@ Author information
The "author information" includes your name, email address, or any other appropriate information. If the "-author" mark is used in the javadoc command line, the author information is extracted from the generated HTML document.

You can use multiple such tags for a series of authors, but they must be placed consecutively. All author information is stored in a separate section of the final HTML code.

6 variable document mark
Variable documents can only include embedded HTML and @ see references.

7. Method document tag
In addition to embedding HTML and @ see references, the method also allows document tags for parameters, return values, and violations.

1. @ param
The format is as follows:
@ Param Parameter Name Description
"Parameter name" refers to the identifier in the parameter list, and "Description" refers to the descriptive text that can be extended to the subsequent line. Once a new document mark is encountered, the previous description ends. You can use any number of descriptions. Each parameter has one.

2. @ return
The format is as follows:
@ Return description
Description indicates the meaning of the returned value. It can be continued into the following rows.

3. @ exception
For details about the "violation" (Exception), we will discuss it in chapter 9th. In short, they are some special objects. If a method fails, they can be "thrown out. When calling a method, although there is only one violation object, some special methods may generate any number of different types of violations. All these violations must be described. Therefore, the format of the violation mark is as follows:

@ Exception full Class Name Description
The full class name explicitly specifies the name of an violation class, which is defined elsewhere. The "Description" (which can also be continued to the following line) tells us why this special type of violation occurs in the method call.

4. @ deprecated
This is a new feature of Java 1.1. This flag indicates that some old features have been replaced by improved new features. The purpose of this tag is to recommend that you do not need to use a specific feature, because this feature may be discarded in future revisions. If you mark a method as @ deprecated, you will receive a warning from the compiler when using this method.