"Crazy Java Handout (3rd edition)". (Li Gang)--notes

1, the necessity of annotation:
1) It is convenient to clarify the process and ideas of this code when you or others reconstruct the system.
2) Increase the readability of your own code.
3) When the code error occurs, the comment code can gradually troubleshoot the error, narrowing the error range (I prefer debug).
2. Annotation type
1) Single-line comment.
Add a double slash to the front of the comment (//)

    publicclass LineComment{    //这是单行注释的范例    publicstaticvoidmain(String args[])    {        //这只是一个单行注释的例子        System.out.println("Single Line Comment");    }}

2) Multiple lines of comments.
Precede the comment with "" To /* start the comment, and end with "" to indicate the end of the comment */ .
Code:

    publicclass MultiCommont{    /*     *这是段注释的一个简单的例子     *这里是函数入口main方法     */    publicstaticvoidmain(String args[])    {        System.out.println("Multi Lines Comments");    }}

3) Documentation comments.
Document comments are a powerful feature in Java that can be used to annotate classes, properties, methods, and so on, and to generate related documents directly from the JDK tool Javadoc, with the basic format of the document comment " /**...*/ ", and not only that the document comment itself has a syntax
Javadoctest: Include comments for classes, methods, member variables

 Packagecom.alex.demo01;/** * Description * <br> website: <a href= "http://blog.csdn.net/qq_32347977" >alex blog </a> * <br> This is a demo of Javadoc * <br> * <br> * <br> * @author Alex * @version 1.0 */ Public  class javadoctest {    /** * Simple Test member variable */    PrivateString name;/** * Main method, program's entry * @param args */     Public Static void Main(string[] args) {System.out.println ("Hello world!"); }}

Test class:

package com.alex.demo01;/** * Description * <br>网站：<a href= "http://blog.csdn.net/qq_32347977">Alex的博客</a> * <br>This is a demo of javadoc * <br> * <br> * <br>  * @author Alex * @version 1.0 */publicclass Test {    /**     * 简单的成员变量     */    privateint age;    /**     * Test的测试构造器     */    publicTest(){    }}

Javadoc command Production API documentation:

-d *Test.java

Parameter details: Enter JAVAODC-HELP on the Windows command line

In order to produce more detailed API documentation, you can use the following Javadoc tags:

[1] Formatting of document and document annotations:
The generated documents are in HTML format, and these HTML-formatted identifiers are not Javadoc, but we write them when we write the comments. Therefore, when formatting the document, you need to include HTML tags appropriately, for example:

/** *This is first line.<br/> *This is second line.<br/> *This is third line.<br/> **/

[2] Three parts of the documentation note:
The document comments can be divided into three sections based on the effect shown in the document, for example:

/** *testDoc方法的简单描述 *<p>testDoc方法的详细说明</p> *@param testInput String 打印输入的字符串 *@return 没有任何返回值 **/publicvoidtestDoc(String testInput){    System.out.println(testInput);}

Summary: In the document, for both the property and the method are existing lists, and then in the following one a detailed description, the list of property names or method names after the description of the paragraph is a summary.
　　
Special note: Except for the two parts above, the last part is the special Description section, the Special Description section uses the Javadoc tag, these are the special marks that the Javadoc tool can parse, which is discussed in the following chapters.
　　
[3] using the Javadoc tag:
　　
Javadoc tags are special tags in Java-inserted document annotations that identify special references in your code. The Javadoc tag consists of the "@" followed by the tag type and the private comment reference. Its format consists of three parts:
　　
@, tag type, private comment reference

Sometimes we can also directly understand the two aspects: @ and the tag type, the special annotation reference; the Javadoc tool resolves special tags embedded in Java document annotations that can help automatically generate a complete formatting API from source code, with tags beginning with the "@" symbol, case-sensitive, Must be entered according to the correct uppercase and lowercase letters. The tag must start at the beginning of a line, otherwise it will be treated as plain text, and the same name tags should be placed together, such as all @see tags should be put together, and then take a look at the meaning of each marker.
　　
@author (1.0): syntax [@author Name-text]
　　
When using the-author option, add a "Author" entry with the specified Name-text when the document is generated, the document comment can contain multiple @author tags, you can specify one or more names for each @author.
@deprecated (1.0): syntax [@deprecated Deprecated-text]
To add a comment, but instead of using the API (although it is available), the Javadoc tool moves Deprecated-text to the front of the description, appears in italics, and adds a bold warning in front of it: "Discourage use." Deprecated-text's first sentence should at least tell the user when to start to discourage the use of the API and what to replace it with. Javadoc only copies the first sentence to the overview section and the index, and the following statement also explains why it is discouraged and should also include a {@link} tag "1.2 version usage" that points to the alternate API
For Javadoc 1.2, use the {@link} tag, which creates inline links where needed, such as:

/** *@deprecated 在JDK X.X中，被{@link #methodName(paramList)}取代 **/

"*: In the upper Mark x.x refers to the JDK version, the link behind the link is the method signature, MethodName for the method name, paramlist for the parameter list"
For Javadoc 1.1, the standard format is to create a @see tag for each @deprecated tag (it is not inline)
　　

@exception(1.0)：语法[@exceptionclass-name description]　　@throws(1.2)：语法[@throwsclass-name description]

The above two tokens are synonyms, using Class-name and description text to add "throw" subheadings to the generated document, where Class-name is the exception name that the method can throw.
　　
{@link} (1.2): syntax [{@link name label}]
　　
Access to an inline link to the specified name in which the syntax for name and label is exactly the same as the @see tag, as described below, but the resulting inline link is not prevented from being linked in the "See" section. The tag starts with curly braces and ends with curly braces to make it different from other inline text, and if you need to use "}" within the tag, use the HTML entity notation directly:
　　

@param(1.0)：语法[@param parameter-name description]

　　
Add parameters to the "See" section, describing the ability to proceed to the next line, mainly by providing some format of the parameters and describing
　　

　@return(1.0)：语法[@return description]

Use description to add the "Return" section, which should describe the return type and allowable range of values
　　
@see (1.0): syntax [@see reference]
　　
The tag is a relatively complex tag that adds a "see" heading with links to reference or text items that can contain any number of @see tags grouped under the same heading, @see in three formats:
@see "string" Note: This form is not used in JDK 1.2, it does not print reference text
Adds a text item to string, does not produce a link, a string is a book or other information reference that is not available through the URL, and Javadoc distinguishes it from the situation by finding the first character as a double quotation mark ("), such as:
@see "This is the Java textbook, mainly for beginners"
The comments above will be generated:
See:
"This is the Java textbook, mainly for beginners"

<a href="page.html#section">Java某章节</a>

Add a link to the Url#value definition, where url#value is a relative URL or an absolute url,javadoc tool to differentiate it from other situations by finding the first character lowercase symbol (<), for example:

<a href="page.html#section">测试规范</a>

The comments above will be generated:
See:
Test specification
@see package.class#member Label "A more commonly used format"
Adds a link to a label with visible text that points to a document of the specified name in the Java language. Where label is optional, if omitted, the name appears as visible text and is embedded in theHTML标记中，当想要缩写可见文本或不同于名字的可见文本的时候，可以使用label。
——package.class#member是Java语言中的任何有效名字——包名、类名、接口名、构造函数名、方法名或域名——除了用hash字符(#)取代成员名前面的点之外，如果该名字位于带文档的类中，则Javadoc将自动创建到它的链接，要创建到外部的引用链接，可使用-link选项，使用另外两种@see形式中的任何一种引用不属于引用类的名字的文档。
——label是可选文本，它是链接的可见标签，label可包含空白，如果省略label，则将显示package.class.member，并相对于当前类和包适当缩短
——空格是package.class#member和label之间的分界符，括号内的空格不表示标签的开始，因此在方法各参数之间可使用空格
@see package.class#member的典型形式
引用当前类的成员

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

Referencing the current package or other classes in the import package

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

referencing 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

A brief description of the @see package:
--the first set of forms (without classes and packages) will cause Javadoc to search only the current class hierarchy. It looks for the current class or interface, its parent class, or a hyper-interface, or a member of its containing class or interface. It does not search for the remainder of the current package or other packages (search step 4-5).
--if any method or constructor is entered as 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, but a warning message will be displayed, prompting for parentheses and arguments to be added. If the method is overloaded, then Javadoc links to the first unspecified method it searches for.
-For all forms, the inner class must be specified as Outer.Inner, rather than as a simple inner.
--as described above, the hash character (#) instead of the dot (.) is used to separate classes and members. This enables Javadoc to parse correctly, because points are also used to separate classes, inner classes, packages, and child packages. When a hash character (#) is the first character, it is absolutely indispensable. However, in other cases, the Javadoc is usually not strict and allows the use of the dot number when there is no ambiguity, but it will display a warning.
The search order for the @see tag--javadoc will process the @see tag that appears in the source file (. java), package file (package.html), or overview file (overview.html), and in the latter two files, you must fully qualify the name provided by @see. In the source file, you can specify a fully qualified or partially qualified name, @see search order:
Current class or interface
Any containing classes and interfaces, first search the nearest
Any parent class and hyper-interface, first search the nearest
Current Package
Any imported packages, classes, and interfaces, searched in the order of the import statements
@since (1.1): syntax [@since Since-text]
Adds a "Since" title to the generated document with the content specified by Since-text, which does not have a special internal structure, which indicates that the change or function has existed since the version of the software specified by Since-text, for example: @since JDK 1.4
@serial (1.2): syntax [@serial field-description]
In the document annotations for the default serializable domain, the optional field-description enhances the ability to describe the document annotation to the field, which must explain the meaning of the field and the acceptable value, if there is a need to describe the number of lines that can be You should add @since tags to each serializable field that you added after the original version of the Serializable class.
@serialField (1.2): syntax [@serialField field-name field-type Field-description]
CV serializable the documentation for the Objectstreamfield component of the Serialpersistentfields member of the class, you should use a @serialfield tag for each Objectstreamfield
@serialData (1.2): syntax [@serialData data-description]
Data-description a document that establishes the sequence and type of data (especially the optional data written by the WriteObject method and all data written by the Externalizable.writeexternal method), @ Serialdata tags can be used in document comments for WriteObject, ReadObject, Writeexternal, and Readexternal methods
@version (1.0): syntax [@version version-text]
When you use the-version option to add a "version" subtitle 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 a maximum of one @version tag.
{@code} (1.5): syntax [{@code text}]
The label is equivalent to{@literal}, you can directly filter out the HTML tag, you can not use < and > to display (< and >), in this block of text, you can write the code directly, even if using theHello, it will not be recognized as a bold hello in HTML, but also the original code snippetHelloThe format output
{@docRoot} (1.3): syntax [{@docRoot}]
Represents the relative path of the generated file (target) from any generated web directory, when you want to include a copyright page or company logo file when it is useful, you want to reference the generated pages, links from each page at the bottom of the copyright page is common. (@docRoot marks can be used on the command line, and in two document comments: This tag is valid in all document annotations: overview, wrapper classes, interfaces, constructs, methods, and realms, including any part of the tagged text (such as @return, @param, and @deprecated use).
Like what:

/**  * See the <a href="{@docRoot}/copyright.html">Copyright</a>.  **/

{@inheritDoc} (1.4): syntax [{@inheritDoc}]
Inherit (copy) the document from the most recent "inheriting class or executable interface" to the current document comment content in the location of this tag, which allows you to write more general documents related to inheritance
The following situation is more appropriate:
In the main description block of a method, in this case, the main description is a copy of the class and interface inside the entire inheritance tree structure.
Methods such as @return @param and @throws are returned in the text parameter, in which case the text marker is a copy of the label inside the entire hierarchy.
{@linkplain} (1.4): syntax [{@linkplain package.class#member label}]
Like {@link}, unless a linked label is displayed in plain text format, the label can work when the text is normal text, for example:

toaddthe overridden method}

This will be shown as:
Refer to the overridden method
{@value} (1.4): syntax [{@value Package.class#field}]
Used primarily to display the value of a static field:

/** * The value of this constant is {@value} **/publicstaticfinal"script";

[4] Examples of Javadoc Tags:
--[$] An example of using the Javadoc tag--

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

For example there is such a small piece of code, on my machine I placed under the D:\Source\work, and then into the directory, using the following command:

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

Using this command, after executing the command, the computer has the following output, and go to the bottom of the directory can see a doc folder, the browser opens inside the index.html can see the content of the generated document:
　　

Loading source File Javadocbasic.Java...Constructing Javadoc Information...Standard Doclet version1.6. 0_16building Tree for AllThe Packages andClasses...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 AllThe Packages andClasses...Generating doc\Overview-tree.Html...Generating doc\Index-all.Html...Generating doc\Deprecated-list.Html...Building Index for AllClasses...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 of using {@link}--

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

Reference: http://my.oschina.net/u/141149/blog/283363

Crazy Java Handouts (3rd edition). (Li Gang)--comment