Comment documentation
For Java languages, the most thoughtful design is that it is not intended to write procedures for writing procedures - people also need to consider the documentation of the program. For the documentation of the program, the biggest problem is the maintenance of the document. If the document is separated from the code, then change the document each time you change the code, this will undoubtedly become a matter of quite trouble. The solution to the method seems to be very simple: the code is "link" with the document. In order to achieve this, the easiest way is to place all content in the same file. However, in order to make everything else, you must also use a special annotation syntax to mark special documents; there is also a tool to extract these comments and display it in valuable form. These are all the Java must do.
Tools used to extract annotations are called Javadoc. It uses some techniques from Java compilers to find special annotation tags we put into programs. It not only extracts information indicated by these tags, but also extracts the class name or method name of the comment. In this way, we can use the lightest workload to generate a professional program documentation.
Javadoc output is an HTML file that can be viewed in your own web browser. This tool allows us to create and manage single source files and vividly generate useful documents. Because of JVADOC, we can create documents with standard methods. And because it is very convenient, we can easily get a document of all Java libraries.
2.8.2 Specific grammar
All javadoc commands can only appear in the "/ **" annotation. But the same is true, the comment ends at a "* /". Mainly in two ways, Javadoc: embedded HTML, or use "document tag". Among them, "Docu Tags" is some command starting with "@", which is placed at the beginning of the annotation line (but the preamble "*" will be ignored).
There are three types of comment documents, which correspond to elements behind comments: class, variables, or methods. That is, a class annotation is just before a class definition; the variable comment is just before the variable definition; and a method definition is just in front of a method definition. As shown in this simple example below:
/ ** A class comment * /
PUBLIC CLASS DOCTEST {
/ ** A variable comment * /
Public INT I;
/ ** A method comment * /
Public void f () {}
}
Note Javadoc can only process an comment document for public (public) and protected members. "Private" and "Friendly" (see 5 chapters) Members are ignored, we can't see any output (you can also use the -Private tag including private members). This is reasonable because only public and protected members can be used outside of the file, which is the hope of the customer programmer. However, all class comments will contain it in the output.
The output of the above code is an HTML file that has the same standard format as other Java documents. Therefore, users will be familiar with this format, which can be easily "roaming" in the class you designed. When designing the program, be sure to consider entering the above code, with Javadoc to process, how to watch the final HTML file.
2.8.3 embed HTML
Javadoc passes the HTML command to the final generated HTML document. This allows us to make full use of huge power of HTML. Of course, our final motivation is formatting code, not for demosol. One example is listed below:
/ **
*
* System.out.println (New Date ());
*
* /
It can also be used to use HTML as in other web documents, format the ordinary text, make it more organized, more beautiful:
/ **
* You or even can insert a list:
*
*
*
*
*
* /
Note that in the document comments, the most beginning of the one-line will be discarded by Javadoc. There is also a leading space at the same time. Javadoc formats all content to match the standard document appearance. Do not use the title of
All types of comments documents - class, variables, and methods - support embedded HTML.
2.8.4 @see: Reference other classes
All three types of comments documents can include @see tags that allow us to reference documents in other classes. For this tag, Javadoc generates the corresponding HTML and links it to another document. The format is as follows:
@see class name
@see full class name
@see Complete Class # method name
Each format will automatically join a hyperlink "See Also" entry in the generated document. Note that Javadoc does not check the hyperlink we specified, and does not verify that they are valid.
2.8.5 class document tag
The class document can also include tags for version information and author names. Class documents can also be used for "interface" purposes (explained later later).
@Version
The format is as follows:
@version version information
Among them, "Version Information" represents any suitable information as version description. If the "-Version" tag is used in the Javadoc command line, the publication information will be extracted from the generated HTML document.
2. @Author
The format is as follows:
@Author Author Information
Among them, "author information" includes your name, electronic letter address, or any other suitable information. If the "-author" tag is used in the Javadoc command line, the author information is extracted specifically from the generated HTML document.
Multiple such tags can be used for a series of authors, but they must be placed continuously. All author information will be deposited in a single paragraph of the final HTML code.
2.8.6 Variable Document Tag
Variable documents can only include embedded HTMLs and @see references.
2.8.7 Method Document Tag
In addition to embed HTML and @see references, the method also allows document tags for parameters, return values, and violations.
@Param
The format is as follows:
@Param parameter name
Where "Parameter" is an identifier within the parameter list, and the "description" represents some instructions that can continue to subsequent lines. Once a new document mark is encountered, it is considered that the previous description ends. Any number of instructions can be used, each parameter.
2. @Return
The format is as follows:
@Return
Wherein, "Description" means the meaning of the return value. It continues to the back of the line.
3. @Exception
We will tell in Chapter 9 about "Exception". Briefly, they are some special objects. If a method fails, they can "throw" objects. When calling a method, although only one violation object appears, some special methods may produce any number, different types of violations. All of these violations need to be explained. Therefore, the format of the violation mark is as follows: @Exception complete class description
Among them, the "full class name" explicitly specifies the name of a violation class, which is defined in other places. "Description" (also continued to the following line) tells us why this special type of violation will appear in the method call.
4. @DepRecated
This is a new feature of Java 1.1. This tag is used to indicate that some old function has been replaced by improved new features. The role of this tag is that users do not have to use a specific function, because this function may be abandoned when the future is revised. If a method is marked as @DepRecated, a warning for the compiler will be received when using this method.
