The 2nd Chapter 2 surprising annotated documents

single-line and multiline comments :

Java inherits the C + + annotation style, uses // makes a single line comment, and uses /**/ to annotate multiple lines of code. Sometimes a multiline comment has a * at the beginning of each line in the middle , but is essentially the same.

Here are two forms of multi-line annotations:

/* This is a comment

* that continues

* Across lines

*/

/* This is a comment that

Continues across lines * *

Comment Document :

Java brings me the biggest surprise or its annotated document, the appearance of the note document link code and documents, for us to avoid the trouble of writing to modify the document, and the resulting HTML document format is also beautiful Cry the.

Javadoc:

Javadoc is the tool used to extract annotations to generate documents, which is part of the JDK. Javadoc not only integrates the information in the annotations, but also extracts the adjacent class names or method names, allowing us to generate good-looking documents with minimal effort.

how to generate :

1. Command line:

javadoc-d Document storage directory -author-version source file name . Java

This command compiles a Java source file named " source file name . Java" and stores the resulting document in the " Document directory " in the specified directory, index.html is the first page of the document in the generated document. -author and -version Two options can be omitted.

2. Eclipse can be exported directly.

comment Syntax :

There are two ways to use Javadoc: Embed HTML and document tags.

"Stand-alone document label": Starts with the "@" character, and the "@" character is placed at the front of the comment line

In-line document label: Starts with the "@" character and can appear anywhere in the Javadoc Comment, but within curly braces.

As the following example:

/** A Class Comment */

public class Doctest {

/** A Variable Comment */

public int i;

/** A Method Comment */

public void F () {}

}

Note thatJavadoc can only document comments for public and protected members. comments for private and accessible members within the package are ignored. However , -private can be used to Mark a private member for processing.

HTML Command Re-embed formatting is not said, the original format is good enough.

Examples of tags :

1. @see: Referencing other classes

@see tags allow you to reference documents from other classes. Javadoc links to other documents in the resulting HTML file, with @see tags. The format is as follows:

@see ClassName

@see Fully-qualified-classname

@see Fully-qualified-classname#method-name

Each format will include a "seeAlso" entry with a hyperlink in the generated document. But Javadoc won't .

Check that the hyperlinks you provide are valid.

2. {@link Package.class#member label}

This tag is very similar to @see, except that it can be used for inline use and "label" as the text of the hyperlink without

"SeeAlso".

3. {@docRoot}

The label produces a relative path to the document root and is used for explicit hyperlinks to the document Tree page.

4. {@inheritDoc}

The tag inherits the relevant document from the most direct base class of the current class into the current document comment.

5. @version

The format of the label is as follows:

@version version-information

where "version-information" can be any important information that you think is appropriate as a release note. If Javadoc

The command line uses the "-version" tag, so you can extract the published information from the generated HTML document.

6. @author

The format of the label is as follows:

@author author-information

Among them, "author-information", words too literally you also know, should be your name, also can include e-mail

Address, or any other appropriate information. If the javadoc command line uses the "-author" label, the author information can be extracted from the generated HTML document.

You can use multiple labels to list all authors, but they must be placed continuously. All author information is merged into

The same paragraph, placed in the generated HTML .

7. @since

This tag allows you to specify the earliest version of the program code that you will see in the HTML Java document that is used to refer to the

Version of the JDK used .

8. @param

The label is used in the method document in the following form:

@param parameter-name Description

where "parameter-name" is the identifier in the method's argument list,the text of "description" can be extended by several lines, ending before the new document label appears. You can use any number of this tag, and about every parameter has one such tag.

9. @return

The label is used for the method document in the following format:

@return Description

where "description" is used to describe the meaning of the return value and can be extended by several lines.

Ten. @throws

"Exception" (Exception) will be discussed in Chapter 9 . In short, they are "thrown" because a method call fails

The object. Although only one exception object appears when a method is called, a particular method may produce any

Different types of exceptions, all of which need to be explained. Therefore, the format of the exception label is as follows:

@throws fully-qualified-class-name Description

where "fully-qualified-class-name" gives the full name of an exception class, and the exception class has

has been defined in a certain place. and "description" (which can also last a few lines) tells you why this particular type of exception will

Appears in the method call.

@deprecated.

This label is used to indicate that some of the old features have been superseded by the improved new features, and it is recommended that users do not use these old features

They are likely to be removed in the near future. If you use a method that is marked as @deprecated , it will be cited

Warning from the compiler.

sample Code : try to generate HTML files Feel the next ~ ~

Hellodate.javaimport java.util.*;/** The first thinking in Java example program.* displays a string and today ' s date.* @ Author Bruce eckel* @author www. bruceeckel.com* @version 2.0*/public class Hellodate {/** Sole entry point to Class & application   * @param args ar  Ray of string Arguments   * @return No return value   * @exception exceptions No exceptions thrown*/public static void Main (string[] args) {    System.out.println ("Hello, it ' s:");    System.out.println (New Date ());}} ///:~

Copyright NOTICE: This article for Bo Master original article, without Bo Master permission not reproduced.

The 2nd Chapter 2 surprising annotated documents