Class annotation document writing method
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 The specific syntax 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: / ** A class comment * / public class doctest {/ ** A variable comment * / public int i; / ** A method comment * / public void f () {}} 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. 3 Embed HTMLJAVADOC Transmit 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.
The following example: / ***
* system.out.println (new date ()); * * / can also use HTML as in other web documents, format ordinary text Chemical, make it more organized, more beautiful: / *** You or even can insert a list: ** Project 1 * project two * project Three * * / Note In the document comment, the most beginning of the talented star 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 or
as embedded HTML, because Javadoc will insert your own title, and we give the title with it. All types of comments documents - class, variables, and methods - support embedded HTML. 4 @see: Referring to all three types of comment documents with other classes can include @see tags, which 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 full class name # Method 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. The 5-class document tags are embedded in HTML and @see, and class documents can also include tags for version information and author name. Class documents can also be used for "interface" purposes (explained later later). 1. @Version format is as follows: @version version information where "Version Information" represents any suitable as a profile. If the "-Version" tag is used in the Javadoc command line, the publication information will be extracted from the generated HTML document. 2. @author 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. 6 Variable Document Tag Variable Documents can only include embedded HTMLs and @see references. 7 Method Document Tag In addition to embed HTML and @see references, the method also allows the use of document tags for parameters, return values, and violations. 1. @Param format is as follows: @Param Parameter name description, "parameter name" is an identifier within the parameter list, and the "description" represents some explanations 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. The @return format is as follows: @Return Description where "Description" means the meaning of the return value. It continues to the back of the line. 3. @Exception For details on "Exception", we will tell it in Chapter 9. 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.
