Javadoc, a fuss over Java annotations __java

Directory

Objective
A. Java documentation and Javadoc
Two. Format of document annotations
1. Formatting of document annotations
2. Three parts of documentation comments
Three. Use Javadoc tags
1. Use of @see
2. Use @author, @version description class
3. Use of @param, @return and @exception description method
Four. Javadoc command

Preface

Java syntax is similar to C + +, so you know how many Java annotations are. are two kinds.

Comment Line
///Comment several lines

Not exactly, in addition to the above two, there is a third, document comments:

/** ... * * Comment several lines and write Javadoc documentation

Typically, the multiple lines of this annotation are worded as follows:

/**
* .........
* .........
*/

Pause, pause. What is the use of this third annotation? Javadoc is something else.

Well, then let me tell you--

A. Java documentation and Javadoc

Java programmers should know that using JDK development, the best help information comes from SUN-published Java documents. It provides a detailed information on the various aspects of the law, the information of the attribute, the detailed tree-like information, the index and so on, and provides the relationship among many related classes, such as inheritance, implementation interface, reference, etc.

Java documents are all organized by a number of HTML files, and they can be downloaded on the SUM site. But you can't imagine that these documents can be built on our own. Stop and hang on to your appetite.

After the JDK is installed, there is a Src.jar file or Src.zip file under the installation directory, which are compressed in zip format and can be decompressed using WINZIP. After decompression, we can see that the sub directory is full of. java files. Yes, these are the Java running class source code, very complete, even the comments are written clearly ... However, how to look at these notes is a little familiar feeling.

It is not surprising that our mystery is about to be uncovered. If you look carefully at the contents of the documentation Comments (/** ... * *) and the Java document in the Java source file, you will find that they are the same. Java documents are just a little bit more in format and typography. A little more careful, you'll find. The annotations in the Java source file also have HTML tags, such as <B>, <BR>, <Code>, and so on, where the identifiers appear in the Java documentation, and are already formatted according to the definition of the identity.

Finally, the original Java document is from these annotations. No wonder these comments are called document annotations. However, what tools make these annotations into documents?

It's time for the Javadoc to come out. You can find Javadoc in the JDK's Bin directory, and if it is a JDK under Windows, its file name is Javadoc.exe. When you compile a. Java source file using Javdoc, it reads the documentation comments from the. Java source file, compiles with Java source programs, and builds the document in accordance with certain rules.

Before you introduce the compilation commands for Javadoc, let's take a look at the format of the documentation comments. However, in order to be able to compile a few examples mentioned below, here is an introduction to the Javadoc command:

javadoc-d Document storage directory-author-version source filename. java

This command compiles a Java source file named "source filename. java" and stores the resulting document in the directory specified in the document storage directory, where index.html is the first page of the document. -author and-version two options can be omitted.

two. Format of document annotations

Document annotations can be used to describe classes, properties, methods, and so on. In addition to the need to use/** when writing documentation comments, you need to pay attention to some of the details inside the annotation.

1. Formatting of documentation and documentation comments

The generated documents are HTML format, and the identifiers for these HTML formats are not Javadoc, but we write them when we write the comments. For example, when you need to change lines, instead of typing a carriage return, write to <br>, and if you want to segment, you should write <p> before the paragraph.

As a result, formatting a document means adding the appropriate HTML identity to the documentation comments.

The body of the document comment is not copied directly to the output file (the document's HTML file), but rather reads each row, deletes the leading * and * number before the space, and then enters the document. Such as

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

The HTML source code after compiling the output is

This is the. <br> This is second line. <br> This is third line.

The leading * number allows continuous use of multiple, the effect is the same as the use of a * number, but the number of * can not be separated by other characters, otherwise the separator and the following * will be the contents of the document. The * number is used here as the left boundary, as in the first and second lines of the preceding example; if there is no leading * number, the boundary begins with the first valid character, excluding the preceding space, as in the third line of the previous example.

It is also important to note that the documentation comment only describes the class, property, or method immediately following it. The following example:

public class Test { int number; public void MyMethod () {...} ...... }

The three comments in the example above are documentation comments on classes, properties, and methods, respectively. The documents they generate are the classes, properties, methods immediately following them. The word "immediately" is particularly important, and if this is omitted, it is likely to cause a generated document error. Such as

Import java.lang.*; public class Test {...}

This documentation comment will generate the correct document. But you just need to change the position of two of the lines, and then the following example will make an error:

Import java.lang.*; public class Test {...}

This example only places the import statement and the document annotation portion of the example in place, and the result is very different--the contents of the comment are not found in the resulting document. why.

"/** Commnet for Class *" is a description of class test, put it in the "public class Test {...}" Before, followed by class Test followed by the rule, so the resulting document is correct. But put it and "import java.lang.*;" After changing the position, the next is not class Test, but an import statement. Because documentation comments can only describe classes, properties, and methods, the import statement is not available, so this document comment is omitted as an error description.

2. Three parts of documentation comments

The document annotation is divided into three parts, depending on the effect shown in the document. The first example is as follows to illustrate.

public void Show (Boolean b) { Frame.show (b); }

The first part is brief. In a document, there is a list of properties and methods before a detailed description of the following one. The description of the property name or method name in the list is briefly described. The red box is selected in the following figure:

The brief section is written at the top of a document's comment, preceded by the first point (.) (including the point number). In other words, a document annotation is separated by the first dot, preceded by a brief, followed by the second and third parts. As in the previous example, the "* Show method is briefly described."

Sometimes, even if it is correctly separated by a point number, Javadoc will still go wrong, and the part that follows the DOT is also the first part. To solve this problem, we can use a <p> logo to open the second part to the next paragraph, as in the previous example, the "* <p>show method of detailed description of the first line ...". In addition, we can use <br> to separate.

The second part is the detailed description section. This section describes the properties or methods in detail, and there are no special requirements in the format, which can contain a number of dots. Its position in the document is shown in the following illustration:

The corresponding code in this section of the document in the previous example is:

* A brief description of the show method.
* Detailed description of the <p>show method the first line <br>
* Show method Details second line

Find out what. By the right, the brief is also in it. Remember this, do not gild the lily--write a brief description in the detail section.

The third part is the special description part. This section includes version descriptions, parameter descriptions, return value descriptions, and so on. Where it is located in the document:

Part Three in the previous example, the corresponding code is

* @param b True to display, False indicates hidden
* @return No return value

In addition to @param and @return, there are other special tags that are used for descriptions of classes, properties, and methods ... Don't push me, I'll say it right away.

three. Use Javadoc tags

Javadoc tags are special tags inserted into document annotations that identify special references in your code. The Javadoc tag consists of "@" and its subsequent tag type and private annotation reference. Remember, three parts--@, tag type, private comment reference. But I'd rather divide it into two parts: @ and tag type, private annotation reference. Although sometimes spaces can be separated between @ and tag types, I prefer to write them next to each other to reduce the chance of error.

The Javadoc tags have the following:

Mark strong> for effect @author The description of the class indicates the author who developed the class module @version td> Description of Class indicates the version of the class module @see Description of classes, properties, methods reference steering, which is the related topic @param Description of method Description of a parameter in method @return description of the method description of the method return value @exception Description of the method Description of exceptions that might be thrown by the method

The tags are described in detail below.

1. Use of @see

There are three kinds of syntax in @see:

@see class Name
@see #方法名或属性名
@see Class Name # Method name or property name

Class name, you can write only the class name (such as String) or write the full name of the class (such as java.lang.String) as needed. So when will you just write out the class name and when you need to write the full name of the class?

If the import statement in the Java source file contains a class, you can write out only the class name, and if it is not, you need to write the full name of the class. Java.lang has also been included by default. This and Javac compiled Java source files, the same rules, so you can simply use Javac compiler to judge, the source program Javac can find classes, Javadoc will also be able to find; Javac cannot find the class, Javadoc also can not find, this need to use the class full name.

Method or property name, if it is a property name, just write out the name of the property, and if it is a method name, you need to write out the method name and the parameter type, and a method with no arguments, you need to write a pair of parentheses. Such as

Member Type	Member names and parameters	@see syntax
Property	Number	@see number
Property	Count	@see Count
Method	Count ()	@see count ()
Method	Show (Boolean B)	@see Show (Boolean)
Method	Main (string[] args)	@see Main (string[])

Sometimes lazy: If the previous example does not have the attribute count, then the reference method count () can be written as @see count. However, for security reasons, it is better to write full @see count ().

The second and third syntax of @see are references to steering methods or attributes, and what are the differences between them?

If the class name is not indicated in the second syntax, the current class is implicitly assumed. So the reference that it defines is shifted to the attributes or methods in this class. And the third syntax indicates the class name, you can also move to other classes of properties or methods.

We give an example of the @see tag. Because @see is the same for class descriptions, property descriptions, and method descriptions, here is only an example of a class description.

public class Testjavadoc { }

The related part of the generated document is as follows:

Both String and StringBuffer are in the Java.lang package, because the package is imported by default, so these two classes can write the class name directly or write the full name of the class. STR, str () are properties and methods with the same name, so the method name needs to be distinguished by (). Main is a method with parameters, so the parameter type is indicated in (). ToString () Although it is also (inherited from object) in this class, we want to refer to the ToString () method of the object class, so we use object#tostring ().

Curiously, why only str, STR () and main (string[]) become links. That is because the compile time does not include the Java.lang package or the stirng, StringBuffer, Object three classes of source files together to compile, so the resulting document does not have information about the three classes, you can not establish a link. The following is a detailed description of the Javadoc compilation command.

In the example above, if you remove the str attribute from the class, what happens to the resulting document? You will find that the original STR, str (), and now become str (), str (), because the str attribute is gone, so Str also represents the method Str ().

2. Use @author, @version description class

The two tags are used to specify the author and version of the class. Javadoc ignores it by default, but command-line switches-author and-version can modify this feature so that the information it contains is output. The syntax of these two marks is as follows:

@author Author name
@version version number

Where @author can be used multiple times to indicate multiple authors, separated by commas (,) between each author in the resulting document. @version can also be used more than once, and only for the first time, the resulting document displays only the version number that is specified for the first use of the @version. The following example

public class Testjavadoc { }

The relevant parts of the generated document are as shown:

As you can see from the diagram of the generated document, two @author statements are compiled and a list of authors is generated in the document. And in two @version statements only the first sentence is compiled and only one version number is generated.

From the diagram, the list of authors is separated by commas, if I want to show the branches. Also, what if I want to display more than two version numbers.

We can combine the above two @author statements into one sentence and combine two @version statements into one sentence:

@author Fancy<br>bird
@version version 1.00<br>version 2.00

The result is as shown in figure:

We have done so to achieve the goal, without destroying the rules. The version number after the @author author name and @version can be any HTML format defined by the user, so we can use the <br> tag to display its branches. Also, the two <br> delimited version numbers are indicated in one @version, and there is no damage to the rule that displays only the first @version content.

3. Use of @param, @return and @exception description method

All three of these tags are used only for methods. @param describes the parameters of the method, @return describes the return value of the method, @exception describes the exception that the method might throw. Their syntax is as follows:

Description of parameters of @param parameter name
@return Return Value Description
@exception Exception class name description

Each @param can only describe one parameter of a method, so if the method requires more than one argument, it needs to be described multiple times using the @param.

Only one @return in a method, and if multiple @return are listed in the documentation description, Javadoc compiles with a warning, and only the first @return is valid in the resulting document.

The exception that the method may throw should be described in @exception. Because a method may throw multiple exceptions, you can have multiple @exception. There should be a brief exception class name behind each @exception, and the reason for throwing an exception should be indicated in the description. 　　It should be noted that the exception class name should be based on the import statement of the source file to determine whether to write the class name or the class full name. Examples are as follows:

public class Testjavadoc { public boolean fun (Integer N) throws Exception { Switch (N.intvalue ()) { Case 0: Break Case 1: throw new Exception ("Test only"); Default return false; } return true; } }

The related parts of the generated document are compiled using Javadoc as follows:

As you can see, @param b excrescent parameter in the example above is superfluous because the argument is just an n and there is not a b but Javadoc is not checked at compile time. Therefore, it is important to correctly match the items in the parameter table and the formal parameter table of the method when writing the document comments. If the parameter in the method parameter table is a, the explanation of the parameter x is given in the document, or one more argument I, it will be confusing. The same is true @exceptin.

The previous example does not throw a nullpointerexception in the program, but why should it be written in a document comment? This is not to demonstrate that redundant exceptions can be compiled, but rather to illustrate the possibility of a run-time (RunTime) exception when writing an exception description. In the example program, if parameter n is a null value (NULL), then the program throws a nullpointerexception at run time, so a description of NullPointerException is added to the documentation comment.

There are two @return statements in the example above, but according to the rule, only the first @return valid in the same method, and the rest will be ignored by Javadoc. Therefore, no description of the second @return appears in the resulting document.

In this case, how to write a document annotation you should already know, and then start to explain the common commands of Javadoc.

four. Javadoc command

Running Javadoc-help can see the usage of Javadoc, here are the common parameters listed below:

Usage:
Javadoc [Options] [packagenames] [SourceFiles]

Options:

	-public	Show only public classes and members
	-protected	Show Protected/public classes and members (default)
	-package	Show Package/protected/public classes and members
	-private	Show all classes and members
	-D <directory>	Destination directory for Output files
	-version	Contains @version segments
	-author	Contains @author segments
	-splitindex	Divide the index into each letter and correspond to a file
	-windowtitle <text>	browser window caption for document

Javadoc can be given a list of packages when compiling a document, or it can be given a list of source program files. For example, under CLASSPATH, there are two packages in several categories as follows:

Fancy. Editor
Fancy. Test
Fancy.editor.ECommand
Fancy.editor.EDocument
Fancy.editor.EView

There are two packages (fancy and Fancy.editor) and 5 classes. Then the compile-time (Windows environment) can use the following Javadoc commands:

Javadoc Fancy/test.java Fancy/editor.java Fancy/editor/ecommand.java Fancy/editor/edocument.java fancy/editor/ Eview.java

This is to give the Java source file as a compilation of parameters, note that the command point is the file path, should be changed according to the actual situation. You can also give a package masterpiece as a compilation parameter, such as:

Javadoc Fancy Fancy.editor

Using the browser to open the Index.html file for the generated document, you can find the difference between the two ways of compiling the results, as shown in the following figure:

The document generated with the second command is divided into three parts: The package list, the class list, and the class description. After a package has been selected in the package list, all classes in the package are listed in the class list, and the Class Description section displays the detailed documentation for that class after a class has been selected in the class list. The document generated with the first command has only two parts, a class list and a class description, and no package list. This is the biggest difference between the two ways to generate documents.

Let's go through the options below.

-public,-protected,-package,-private four options, you only need to choose one. The extent to which they specify the display class members. The number of members they display is a contained relationship, as in the following table:

-private (Show all classes and members)

-package (show Package/protected/public classes and members) -protected (show Protected/public classes and members) -public (show only public classes and members)

The-D option allows you to define the output directory. If you do not use the-D definition output directory, the resulting document files are placed in the current directory. Use of the-D option is

-D directory Name

The directory name is required, that is, if you use the-D argument, you must specify a directory for it. This directory must already exist, and if it does not exist, create the directory before running Javadoc.

-version and-author are used to control whether @version and @author-specified content are generated when the document is generated. Without these two parameters, the resulting document does not contain version and author information.

The-splitindex option divides the index into one file for each letter. By default, there is only one index file, and all indexed content is included in the file. Of course, it would be a good time to generate a little bit of documentation, but if there's a lot of documentation, the index file will contain a lot of content and it's too big. Using-splitindex, the index file is sorted by the first letter of each index entry, and each letter corresponds to a file. This reduces the burden on an index file.

The-windowtitle option assigns a title to the document, which appears on the title bar of the window. If you do not specify the caption, the default document title is the resulting document (no title). The use of this option is:

-windowtitle Title

A caption is a string of text that does not contain spaces, because spaces is used to separate arguments, so it cannot contain spaces. Similar to-D, you must specify the caption text if the-windowtitle option is specified.

So far, the Java documentation and Javadoc are done. Javadoc really allows us to make a fuss about Java annotations--generating development documentation.