Java experience bit: class Annotation Document writing method _java programming

Article Source: csdn Author: chensheng913

One of the most thoughtful designs for the Java language is that it doesn't plan to have people write programs to write programs--people also need to think about the documentation of the program. The biggest problem with documentation for a program is the maintenance of the document. If the document is separated from the code, changing the document every time you change the code will undoubtedly become a rather troublesome thing.

The solution seems simple: link the code to the document. The easiest way to do this is to put everything in the same file. However, in order to make everything uniform, you must also use a special annotation syntax to mark out special documents, and a tool to extract the annotations and show them in a valuable form. That's all Java has to do.

The tool used to extract annotations is called Javadoc. It uses some technology from the Java compiler to find special annotation tags for our placement programs. It extracts not only the information indicated by these tags, but also the class name or method name of the adjacent annotation. As a result, we can generate very professional program documentation with the lightest amount of work.
Javadoc outputs an HTML file that can be viewed in its own web browser. This tool allows us to create and manage a single source file and to produce useful documents graphically. With Jvadoc, we were able to create documents in a standard way. And because it's very convenient, we can easily get all the Java library documentation.

2 Specific grammars

All Javadoc commands can only appear in the "/**" comment. But peace is always the same, the annotation ends with a "* *". There are two main ways to use Javadoc: embedded HTML, or use document markup. where document tags (doc tags) are commands that begin with "@" and are placed at the beginning of the comment line (but the leading "*" is ignored).
There are three types of annotation documents that correspond to the elements that are behind the annotation: class, variable, or method. That is, a class annotation is just before a class definition, the variable annotation is just before the variable definition, and a method definition is right in front of a method definition. As shown in the following simple example:

/** a class Comment * * public class Doctest { /** a variable comment * * public int i; /** a method Comment * * public void F () {} }

Note Javadoc can only process the annotation document for public and protected (protected) members. Comments for members of private and friendly (see chap. 5) are ignored, and we do not have any output (and can also include private members with-private tags). This makes sense because only public and protected members can be used outside of the file, which is the hope of the client programmer. However, all class annotations will be included in the output result.
The output of the above code is an HTML file that has the same standard format as other Java documents. As a result, users are very familiar with this format and can easily "roam" through the classes you design. When you design your program, be sure to consider entering the code above and using Javadoc to see how the final HTML file will look.

3 Embedding HTML
Javadoc passes HTML commands to the resulting HTML document. This allows us to take full advantage of the immense power of HTML. Of course, our ultimate motivation is to format code, not to impress. An example is listed below:

/** * * SYSTEM.OUT.PRINTLN (new Date ()); * */ You can also use HTML as in other Web documents to format plain text to make it more organized and aesthetically pleasing: /** * You can even insert a list: * * Project A * Item Two * Item Three * */

Note In a document comment, the asterisk at the beginning of a line is discarded by Javadoc. Also discarded is a leading space. Javadoc formats all of the content to match the standard document appearance. Do not put
Or

Such headings are used as embedded HTML because Javadoc inserts its own title, and the title we give will collide with it.
All types of annotation documents-classes, variables, and methods-support embedding HTML.

4 @see: Referencing other classes
All three types of annotation documents can contain @see tags, which allow us to refer to documents in other classes. For this tag, Javadoc generates the appropriate HTML and links it directly to other documents. The format is as follows:

@see class Name
@see Full class name
@see Full class name
Each format will automatically include a hyperlink's "See Also" entry in the resulting document. Note that Javadoc does not check the hyperlinks we specify and does not verify that they are valid.

5 Class Document tags
With embedded HTML and @see references, class documents can also include tags for version information and author names. Class documents can also be used for "interface" purposes (explained in detail later in this book).

1. @version
The format is as follows:
@version Version Information
The "version information" represents any information that is appropriate for the version description. If the "-version" tag is used on the Javadoc command line, the published information is extracted from the generated HTML document.

2. @author
The format is as follows:
@author Author Information
The "Author information" includes your name, e-mail address, or any other appropriate information. If the "-author" tag is used on the Javadoc command line, author information is extracted specifically from the generated HTML document.
You can use multiple such tags for a series of authors, but they must be placed continuously. All author information is stored together in a separate paragraph in the final HTML code.

6 Variable Document Markers
Variable documents can only include embedded HTML and @see references.

7 Method Document Tags
In addition to embedding HTML and @see references, methods allow you to use document tags for parameters, return values, and violations.

1. @param
The format is as follows:
@param parameter Name Description
where "parameter name" refers to an identifier within the parameter list, and "description" represents some descriptive text that can be persisted to subsequent lines. Once a new document tag is encountered, the previous description is considered to end. You can use any number of descriptions, one for each parameter.

2. @return
The format is as follows:
@return Description
Where "description" refers to the meaning of the return value. It can be extended to the back of the line.

3. @exception
Details of the "contravention" (Exception) will be covered in chapter 9th. In short, they are special objects that, if a method fails, can be "thrown out" of the object. When a method is invoked, although only one of the offending objects appears, some special methods may produce any number of different types of violations. All these violations need to be explained. Therefore, the format of the offence markings is as follows:
@exception Full class name description
The "Full class name" explicitly specifies the name of an offending class, which is defined elsewhere. The "description" (which also extends to the line below) tells us why this particular type of violation appears in the method call.

4. @deprecated
This is a new feature of Java 1.1. This tag is used to indicate that some of the old features have been replaced by new, improved functionality. The role of this tag is to recommend that users do not have to use a particular feature, because it may be discarded in future revisions. If you mark a method as @deprecated, you receive a warning from the compiler when you use this method.