Crazy Java handout (version 3rd). (Li Gang) -- Comment

Crazy Java handout (version 3rd). (Li Gang) -- Comment

1. Necessity of annotation:
1) You or others can easily understand the process and ideas of this code when restructuring the system.
2) increase the readability of your code.
3) When an error occurs in the code, you can annotate the code to gradually troubleshoot the error and narrow down the error scope (I prefer debug ).
2. annotation type
1) single line comment.
Add a double slash to the front of the comment (//)

Public class LineComment {// This is an example of single-line annotation public static void main (String args []) {// This is just an example of single-line annotation System. out. println ("Single Line Comment ");}}

2) multi-line comment.
Add"/*"Indicates that the comments start and end with"*/"Indicates the end of the comment.
Code:

Public class MultiCommont {/** this is a simple example of segment annotation * here is the main method of the function entry */public static void main (String args []) {System. out. println ("Multi Lines Comments ");}}

3) document comments.
Document annotation is a powerful function in Java. It can be used to annotate classes, attributes, methods, and other instructions. In addition, the JDK tool javadoc directly generates relevant documents, the basic format of the document comment is"/**...*/Not only that, but there are still syntaxes in the document annotations.
JavadocTest: includes comments of classes, methods, and member variables.

Package com. alex. demo01; /*** Description ** This is a demo of javadoc *** @ author Alex * @ version 1.0 */public class JavaDocTest {/*** simple test member variable */ private String name; /*** main method, program entry * @ param args */public static void main (String [] args) {System. out. println ("Hello World! ");}}

Test class:

Package com. alex. demo01; /*** Description ** This is a demo of javadoc *** @ author Alex * @ version 1.0 */public class Test {/*** simple member variable */ private int age; /*** Test constructor */public Test (){}}

Javadoc command production api documentation:

javadoc -d *Test.java

Parameter description: Enter javaodc-help in the windows command line.

To produce more detailed api documentation, you can use the following javadoc Tag:

[1] formatting of documents and comments:
The generated documents are in HTML format, and the identifiers in HTML format are not added by javadoc, but written when writing comments. Therefore, when formatting a document, you must add HTML tags as appropriate. For example:

/** *This is first line. *This is second line. *This is third line. **/

[2] three parts of the document comment:
According to the effect shown in the document, the document comment can be divided into three parts. Here is an example:

/*** Simple description of the testDoc Method *

Detailed description of the testDoc Method

* @ Param testInput String print input String * @ return no return value **/public void testDoc (String testInput) {System. out. println (testInput );}

Brief description: In this document, the attribute and method are both in the existing list, and then detailed descriptions are provided one by one. The description after the attribute or method name in the list is described briefly.
　　
Special note: In addition to the above two parts, the last part is the special note part. The special note part uses the JavaDoc mark, which are the special marks that the JavaDoc tool can parse, this will be discussed in the following sections.
　　
[3] Mark with javadoc:
　　
The javadoc mark is a special mark in the java insert document comment, which is used to identify special references in the code. The javadoc tag consists of "@" and the subsequent tag type and special annotation reference. The format includes three parts:
　　
@, Tag type, special comment reference

Sometimes we can also understand it as two aspects: @ and tag type, special annotation reference; Javadoc tool can parse the special mark embedded in the Java document annotation, these document tags help to automatically generate a complete formatting API from the source code. They start with the "@" symbol and are case sensitive and must be entered with correct uppercase/lowercase letters. The tag must start with a line. Otherwise, it will be considered as a common text and the tags with the same name should be put together as required. For example, all @ see tags should be put together, next, let's take a look at the meaning of each tag.
　　
@ Author (1.0): syntax [@ author name-text]
　　
When the-author option is used, add the "Author" item when the specified name-text is used to generate the document. The document annotation can contain multiple @ author tags, you can specify one or more names for each @ author.
@ Deprecated (1.0): syntax [@ deprecated-text]
Add comments, but you should not use this API again (although it is available). The Javadoc tool will move deprecated-text to the front of the description, display it in italic, and add a warning in bold before it: "not encouraged ". The first sentence of deprecated-text should at least tell the user when to encourage or replace the API. Javadoc only copies the first sentence to the overview part and the index. The following statement can explain why it is not encouraged. It should also include a {@ link} Mark pointing to the alternative API [version 1.2 usage]
For Javadoc 1.2, use the {@ link} tag, which will create embedded links as needed, such:

/*** @ Deprecated is replaced by {@ link # methodName (paramList)} in jdk x. X **/

[*: In the above mark, X. X indicates the JDK version. The link behind it is the method signature, methodName is the method name, And paramList is the parameter list]
For Javadoc 1.1, the standard format is to create a @ see tag for each @ deprecated tag (it cannot be embedded)
　　

@ Exception (1.0): syntax [@ exception class-name description] @ throws (1.2): syntax [@ throws class-name description]

The above two tags are synonyms. Use the class-name and description text to add a "throw" Subtitle to the generated document. The class-name is the exception name that can be thrown by this method.
　　
{@ Link} (1.2): syntax [{@ link name label}]
　　
The syntax of the name and label in the mark is exactly the same as that in the @ see Mark, as described below, but the generated embedded link does not prevent the link in the "see" section. This tag starts with curly braces and ends with curly braces to distinguish it from other embedded texts. If you need to use "}" in the tag, use the HTML Entity notation directly:
　　

@ Param (1.0): syntax [@ param parameter-name description]

　　
Add parameters to the "see" section. The description can be used to continue to the next line. It mainly provides the format and description of some parameters.
　　

@ Return (1.0): syntax [@ return description]

Use description to add the "return" section. This text should describe the return type and permitted range of the value.
　　
@ See (1.0): syntax [@ see reference]
　　
This tag is a relatively complex tag. You can add a "see" title with links or text items pointing to the reference. The document comment can contain any number of @ see tags, they are all grouped under the same title, and @ see has three formats:
@ See "string" Note: This form is useless in JDK 1.2 and does not print reference text
Add text items to the string without generating links. The string is referenced by books or other information that are unavailable to the URL. Javadoc searches for double quotation marks (") as the first character (") to distinguish the frontend, for example:
@ See "This is a Java teaching material, mainly for beginners"
The above comment will generate:
See:
"This is a Java teaching material, mainly for beginners"

@ See a Java chapter

Add the URL # value-defined link. The URL # value is relative to the URL or absolute URL. The JavaDoc tool identifies it from other situations by searching for the first character in lower case (<), for example:

@ See Test Specification

The above comment will generate:
See:
Test Specification
@ See package. class # member label [a common format]
Add a link with a visible text label pointing to the document with the specified name in Java. The label is optional. If omitted, the name appears as visible text and is embedded inIn HTML Tag, you can use label when you want to abbreviated visible text or visible text different from the name.
-- Package. class # member is any valid name in the Java language-package name, class name, Interface Name, constructor name, method name, or domain name-except for the hash character (#) in addition to the point before the member name, if the name is located in the class with the document, Javadoc will automatically create a link to it and create a reference link to the outside, you can use the-link option to reference a document that does not belong to the referenced class name in the other two @ see forms.
-- Label is an optional text. It is a visible link label that can contain white space. If label is omitted, the package. class. member is displayed, Which is shortened as appropriate to the current class and package.
-- Space is the delimiter between package. class # member and label. The space in the brackets does not indicate the start of the label. Therefore, spaces can be used between parameters of the method.
@ See package. class # typical member format
Reference members of the current class

@see #field@see #method(Type,Type,...)@see #method(Type argname,Type argname,...)

Reference the current package or other classes in the import package

@see Class#field@see Class#method(Type,Type,...)@see Class#method(Type argname,Type argname,...)@see Class

Reference other packages (fully qualified)

@see package.Class#field@see package.Class#method(Type,Type,...)@see package.Class#method(Type argname,Type argname,...)@see package.Class

@ See package:
-- The first form (no class or package) will cause Javadoc to only search for the current class hierarchy. It searches for the current class or interface, its parent class or super interface, or its members that contain the class or interface. It does not search for the remaining parts of the current package or other packages (search for steps 4-5 ).
-- If any method or constructor input is a name without parentheses, such as getValue, and if there is no domain with the same name, Javadoc will correctly create a link to it, however, a warning message is displayed, prompting you to add parentheses and parameters. If this method is overloaded, Javadoc will link to the first method that it has not specified.
-- For all forms, the internal class must be specified as outer. inner, rather than a simple inner.
-- As described above, the hash character (#) instead of the dot (.) is used to separate classes and members. This allows Javadoc to be correctly parsed because vertices are also used to separate classes, internal classes, packages, and sub-packages. When the hash character (#) is the first character, it is absolutely indispensable. However, in other cases, Javadoc is generally not strict and allows the use of a dot when there is no ambiguity, but it will display a warning.
The @ see Mark in the "Limits" file. In the last two types of files, you must use the name provided by "@ see". In the source file, you can specify a fully qualified or partially qualified name, @ see:
Current class or interface
Search for the nearest class and Interface
Search for the nearest parent class and superinterface
Current package
Any import packages, classes, and interfaces are searched in the order of import statements
@ Since (1.1): syntax [@ since-text]
Add the "since" title to the generated document with the content specified by Since-text. The text has no special internal structure, this flag indicates that the change or feature exists after the software version specified by since-text, for example: @ since JDK 1.4
@ Serial (1.2): syntax [@ serial field-description]
The optional field-description in the document comment for the default serializable domain enhances the ability of the document comment to describe the domain, the combination description must explain the meaning of the domain and list acceptable values. If you need to describe multiple rows, add the @ since Mark to each Serializable domain added after the initial version of the Serializable class.
@ SerialField (1.2): syntax [@ serialField field-name field-type field-description]
The document of the ObjectStreamField component of the serialPersistentFields Member of the resume Serializable class. Each ObjectStreamField should be marked with a @ serialField
@ SerialData (1.2): syntax [@ serialData data-description]
Data-description: creates data (especially the optional data written by the writeObject method and Externalizable. all data written by the writeExternal method) A document of the sequence and type. The @ serialData mark can be used in the comments of the writeObject, readObject, writeExternal, and readExternal methods.
@ Version (1.0): syntax [@ version-text]
When the-version option is used, the "version" subtitle is added to the generated document with the content specified by version-text. The text does not have a special internal structure, and the document comment can contain at most one @ version mark.
{@ Code} (1.5): syntax [{@ code text}]
This tag is equivalent{@literal}, Which can directly filter out HTML tags and can be displayed without <and> (<and>). In the text part of the code block, you can directly write the code, even if you useHelloIn HTML, it will not be recognized as a bold Hello, but it is still the original code segment.HelloFormat output
{@ DocRoot} (1.3): syntax [{@ docRoot}]
Represents the root of the file (target) generated by the relative path from any generated webpage directory. It is useful when you want to include a copyright page or company logo file, you need to reference the generated webpage. links from the bottom of each page are common. (@ DocRoot will mark can be used in the command line, and in two documents Note: This mark is valid, in all documents Note: Overview, packaging class, interface, constructor, method and field, include any part of the markup text (for example, @ return, @ param, and @ deprecated ).
For example:

/**  * See the Copyright.  **/

{@ InheritDoc} (1.4): syntax [{@ inheritDoc}]
Inherit (copy) the document from the latest "inheritance class or executable interface" to the document comment content at the current location of this tag, this allows you to write more general documents related to inheritance.
The following situations are suitable:
In this case, the main description block of a method is a copy of the classes and interfaces in the inherited tree structure.
The @ return @ param and @ throws Methods returned by the text parameter are marked. In this case, the text mark is a copy of the labels in the entire hierarchy.
{@ Linkplain} (1.4): syntax [{@ linkplain package. class # member label}]
Similar to {@ link}, unless the label of the link is displayed in the format of plain text, the label can work when the text is plain text. For example:

Refer to {@linkplain add() the overridden method}

This will be displayed:
Refer to the overridden method
{@ Value} (1.4): syntax [{@ value package. class # field}]
It is mainly used to display the values of static fields:

/** * The value of this constant is {@value} **/public static final String SCRIPT_START = "script";

[4] JavaDoc tag example:
-- [$] An Example of marking with JavaDoc --

/** * @author Lang Yu * @version 1.2 */public class JavaDocBasic {    /**     * @see "Main Function JavaDoc"     * @since JDK 1.4     * @param args The params of console     **/    public static void main(String args[]){        System.out.println("Hello World!");    }}

For example, if there is such a short piece of code, I put it under D: \ Source \ work on my machine, then enter the directory, and use the following command:

D:\Source\work>javadoc -d doc JavaDocBasic.java

Then you can see the content of the generated document:
　　

Loading source file JavaDocBasic.java...Constructing Javadoc information...Standard Doclet version 1.6.0_16Building tree for all the packages and classes...Generating doc\JavaDocBasic.html...Generating doc\package-frame.html...Generating doc\package-summary.html...Generating doc\package-tree.html...Generating doc\constant-values.html...Building index for all the packages and classes...Generating doc\overview-tree.html...Generating doc\index-all.html...Generating doc\deprecated-list.html...Building index for all classes...Generating doc\allclasses-frame.html...Generating doc\allclasses-noframe.html...Generating doc\index.html...Generating doc\help-doc.html...Generating doc\stylesheet.css...

-- [$] An example using {@ link --

/** * @author Lang Yu * @see java.lang.String */public class JavaDocLink {    private int a;    private int b;    /**     * {@link #getAdd() getAdd()} Method     * @return the result of (a + b)     **/    public int getAdd(){        return a + b;    }}