Welcome to the Csdn-markdown Editor

Javadoc Annotation Specification

• 1. Comment classification
• 2. Java Documentation and Javadoc
• 3. Format of document annotations
  
  • 3.1 Formatting of document and document annotations
  • 3.2 Part Three of the documentation note
• 4. Using the Javadoc tag
  
  • Use of 4.1 @see
  • 4.2 @author, @version description class
  • 4.3 Use of @param, @return and @exception
• 5. Javadoc command
• 6. Examples of annotations

1. Comment classification

There are three categories of Java annotations:
1.//Comment Line
2./*-*/note several lines
3./* * / comment Several lines and write to the Javadoc document *

2. Java Documentation and Javadoc

Java programmers should know that using JDK development, the best help information comes from SUN's published Java documentation. It provides the help information of various parties ' laws and attributes in detail, with detailed tree information, index information and so on, and provides relationships among many related classes, such as inheritance, implementation interface, reference, etc.

Java documents are all organized by some HTML files, and they can be downloaded at the SUM site. But you can't imagine that we can generate these documents ourselves.

After installing the JDK, there is a Src.jar file or Src.zip file in the installation directory, which is compressed in zip format and can be decompressed using WINZIP. After unpacking, we can see that the sub-directory is full of. java files. Yes, these are the Java operating class source, very complete, even the comments are written clearly

Take a closer look at the documentation comments in the Java source file (/* ... ). /) and the contents of the Java documentation, you will find that they are the same. More carefully, you will find. Comments in the Java source file also have HTML identifiers, such as ,
, , and so on, where these identities appear in the Java documentation and are already formatted as defined by the identity.

In the bin directory of the JDK you can find Javadoc, if it is a JDK under Windows, its file name is Javadoc.exe. When compiling a. Java source file using Javdoc, it reads out the document comments in the. Java source file and compiles it along with the Java source program according to certain rules, generating the document.

To be able to compile some of the examples mentioned below, here is a Javadoc command: javadoc-d document storage directory-author-version source file name. Java This command compiles a Java source file named "source file name. Java", The resulting document is stored in the directory specified in the document directory, and Index.html is the first page of the document in the generated document. Options are available on both-author and-version.

3. Format of document annotations

Document annotations can be used to describe classes, properties, methods, and so on. Write document comments In addition to using/* ... . /qualification, you also need to be aware of some of the details inside the note.

3.1 Formatting of document and document annotations

The generated documents are in HTML format, and the identifiers of these HTM formats are not javadoc, but we write them when we write the comments. For example, instead of typing a carriage return, you would write
if you want to break a line, and you should write

Before the segment if you are segmenting.

Therefore, formatting the document means adding the appropriate HTML identifier to the document comment.

The body of the document comment is not copied directly to the output file (the document's HTML file), but after each line is read, the leading * number and the previous space of the * number are deleted and then entered into the document. Such as:
/**
* This was first line.

* This was second line.

This was third line.
*/

The HTML source code after compiling the output is:
This was first line.

This was second line.

This was third line.

The leading * number allows for continuous use of multiple, with the same effect as using a * number, but there can be no other characters separated by multiple * numbers, otherwise the delimiter and subsequent * numbers will be the contents of the document.

It is also important to note that documentation comments only describe the class, property, or method immediately following it. The following example:
/* Comment for class /
public class Test {

/* Comment for a attribute /
int number;

/* Comment for a method /
public void MyMethod () {
......
}
......
}

The three comments in the previous example are document annotations to classes, properties, and methods, respectively. They generate documents that describe the classes, properties, methods, and so on, which are immediately followed. the word "immediately" is especially important, and if this is omitted, it is likely that the resulting document will be wrong. Such as:
Import java.lang.*;

/* Commnet for class /
public class Test {...}

This example is the correct example

This document comment will generate the correct document. But you just need to change the position of two of these lines, and the following example will make an error:
/* Commnet for class /

Import java.lang.*;

public class Test {...}

This example is an example of an error

This example swaps the import statement of the previous example with the document Comment section, but the result is very different-the resulting document cannot find the above comment at all.

/* Commnet for Class /is a description of class test, put it in public class Test {...} Before, followed by class Test, conforms to the rules, so the resulting document is correct. But it and "import java.lang.*; After the change of position, followed by a non-class Test, but an import statement." Because document annotations can only describe classes, properties, and methods, the import statement is not listed, so this document comment is omitted as an error description.

3.2 Part Three of the documentation note

The document comments are divided into three parts, depending on the effect shown in the document. Let's give an example to illustrate this.

/**
* A brief description of the show method.
*

Detailed description of the Show method first line

* Detailed description of the Show method the second line
* @param b True indicates display, false means hidden
* @return No return value
*/
public void Show (Boolean b) {
Frame.show (b);
}

The first part is a summary, the description after the attribute name or method name in the list is a summary. A brief description is written before the first dot (.) in a document comment, including the point number. In other words, the document comments are separated by the first dot, preceded by a brief description, followed by the second and third parts. As in the example above, "* The description of the show method."

Sometimes, even if a dot is correctly delimited, Javadoc will still go wrong, and the part behind the dot is also done for the first part. To solve this problem, we can use a

flag to separate the second part, as in the previous example, the "*

Show method details the first line ...".

The second part is the detailed description section. This section describes the properties or methods in detail, there are no special requirements in the format, and can contain several dot numbers.

The third part is the Special Description section. This section includes release notes, parameter descriptions, return value descriptions, and so on. In the third part, the corresponding code in the example above is:
* @param b True indicates display, false means hidden
* @return No return value
In addition to the @param and @return, there are other special tags for descriptions of classes, properties, and methods, respectively.

4. Using the Javadoc tag

Javadoc tags are special tags that are inserted into document comments that identify special references in your code. The Javadoc tag consists of the tag type and the private comment reference followed by "@". Remember, three parts--@, tag type, private comment reference. While the @ and tag types can sometimes be separated by spaces, it is recommended to write them next to each other to reduce the chance of error.

The Javadoc tags have the following:

Use of 4.1 @see

There are three types of syntax for @see:
1. @see Class Name
2. @see #方法名或属性名
3. @see Class Name # Method name or property name

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

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 out the class name. Java.lang has also been included by default. This and Javac compile Java source files when the same rules, so you can simply use Javac compile to judge, the source program Javac can find the class, Javadoc will be able to find, Javac can not find the class, Javadoc can not find, this requires the use of the class name.

The method name or attribute name, if it is a property name, you only need to write out the property name, if it is the method name, you need to write out the method name and parameter type, there is no parameter method, you need to write out a pair of parentheses. Such as

Sometimes lazy: If the previous example does not have the Count attribute, then the reference method count () can be simply written @see count. However, for security reasons, it is better to write a full @see count ().
What is the difference between the second and third syntax of the @see, which are the reference to the steering method or attribute?
The second syntax does not indicate the class name, then it defaults to the current class. So the reference to its definition is shifted to the properties or methods in this class. The third syntax, which indicates the class name, can also be turned to the properties or methods of other classes.
For a @see tag, let's give an example. Since @see are used in the same way as for class descriptions, property descriptions, and method descriptions, this is only an example of a class description.
/**
* @see java.lang.String
* @see #str
* @see #str ()
* @see #main (string[])
* @see java.lang.object#tostring ()
*/
public class Testjavadoc
{
Private String str;
public void Str () {
}
public static void Main (string[] args) {
}
}
The relevant parts of the generated document are as follows:

String This class can write directly to the class name or write the class name. STR, str () are attributes and methods of 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 () also has (inherited from object) in this class, but we want to refer to the ToString () method of the object class, so Object#tostring () is used.
Why is it that only str, str (), and Main (string[]) become links? That is because the Java.lang package is not compiled together, so the resulting document does not have information about the three classes, and it is not possible to establish a link. The following explanation of the Javadoc compile command will be explained in detail.

4.2 @author, @version description class

These two tags are used to indicate the author and version of the class. By default Javadoc ignores it, but command-line switches-author and-version can modify this feature so that the information it contains is output. The syntax for these two tokens 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, only the first time it is valid, the resulting document will only show the version number indicated by the first use @version. The following example
/**
* @author Fancy
* @author Bird
* @version version 1.00
* @version version 2.00
*/
public class Testjavadoc {
}
Generating relevant parts of a document

From the diagram, the list of authors is separated by commas, what if I want to display a branch? Also, what if I want to show 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
Bird
@version version 1.00
version 2.00
Results

We have done so in order to achieve our goal without breaking the rules. Both the author name after @author and the version number after @version can be any HTML format that is defined by the user, so we can use the
tag to display its branches.

4.3 Use of @param, @return and @exception

These three tokens 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:
Parameter description of the @param argument name
@return Return Value Description
@exception Exception class name description
Each @param can only describe one parameter of the method, so if the method requires more than one parameter, it needs to be described multiple times using the @param.
Only one @return can be used in a method, and if more than one @return is listed in the document description, a warning is issued when the Javadoc compiles, and only the first @return is valid in the resulting document.
The exceptions that the method may throw should be described in @exception. Because a method may throw multiple exceptions, you can have multiple @exception. Each @exception should have a description of the exception class name, which should indicate why the exception was thrown. 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 out the class name or class full name. Examples are as follows:
public class Testjavadoc {
/**
* @param n A switch
* @param b excrescent parameter
* @return True or False
* @return Excrescent return
* @exception java.lang.Exception Throw when switch is 1
* @exception nullpointerexception Throw when parameter n is null
*/
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 relevant parts of the document generated using Javadoc compilation are as follows:

As you can see, the @param b excrescent parameter in the previous example is superfluous because the parameter is just an n and does not have a B. However, Javadoc is not checked at compile time. Therefore, it is important to correctly match the parameter table and the item in the formal parameter table of the method when writing the document annotation. If the parameter in the method parameter table is a, the document gives an explanation of the parameter x, or one more argument I, it can be confusing. @exceptin is the same.
The above example does not throw a nullpointerexception, but why does it have to be written in a document comment? This is not to demonstrate the possibility of describing redundant exceptions, but also to compile, but to illustrate the likelihood of a run-time (runtime) exception when writing an exception description. In the above procedure, if the parameter n is null (NULL), then the program throws a nullpointerexception at run time, so the description of NullPointerException is added to the document comment.
The @return statement in the previous example has two, but according to the rule, only the first @return is valid in the same method, and the remainder is ignored by Javadoc. Therefore, the second @return description does not appear in the resulting document.

5. Javadoc command

Run : Javadoc-help can see the use of Javadoc, here are the following list of common parameters:
usage : Javadoc [Options] [packagenames] [SourceFiles]
Options :

              -public show only public classes and members
              -protected display protected/public classes and members (default)
           &N Bsp  -package display Package/protected/public classes and members
              -private Show All classes and Member
              -d output file target directory
       &NB Sp      -version includes @version segment
              -author contains @author segments
              -splitindex to divide the index into each letter,         files
&N Bsp             -windowtitle document browser window title

Javadoc can be given a list of packages when compiling a document, or a list of source program files. For example, under CLASSPATH there are two packages of several classes 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 compile-time (Windows environment) can use the following Javadoc command:

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 method of compiling parameters, note that the command points to the file path, should be changed according to the actual situation. It can also be given a package masterpiece as a compilation parameter, such as:

Javadoc Fancy Fancy.editor

Open the index.html file of the generated document in a browser to discover the differences between the two ways of compiling the results, such as:

The document generated with the second command is divided into three parts: A package list, a class list, and a class description. After a package is selected in the package list, all classes in the package are listed in the class list, and after a class is selected in the class list, the class Description section displays a detailed document of the class.
Here's a more elaborate option.
-public,-protected,-package,-private four options, you only need to select one. They specify the degree to which the class members are displayed. The number of members they display is a contained relationship, as follows:

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

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

-D directory Name

The directory name is required, meaning that if you use the-d parameter, 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 to generate @version and @author specified content 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 per letter. By default, the index file has only one, and the file contains all indexed content. Of course it's a good thing to do when you don't have a lot of document content, but if the content of the document is very large, the index file will contain a lot of content. Using-splitindex, the index file is categorized 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 caption to the document, which appears on the title bar of the window. If you do not specify the caption, the default document title is "generated document (untitled)". The use of this option is:

-windowtitle Title

The caption is a string of text that contains no spaces, because whitespace is used to separate parameters, so it cannot contain spaces. Similar to-D, if you specify the-windowtitle option, you must specify the caption text.

6. Note Examples refer to Java official

Code comment is a bridge between the program designer and the program reader, which maximizes team development cooperation efficiency. is also one of the important parts of the program code maintainability.


principles:
1.Uniform annotation Form
Throughout your application, you construct annotations using styles that have consistent punctuation and structure. If you find in other projects that their annotation specifications are different from this document, write the code in accordance with this specification, and do not attempt to introduce new specifications into the established canonical system.
1.note content is accurate and concise
The content should be simple, clear, meaning accurate, prevent the ambiguity of annotations, wrong comments not only useless but harmful.


Comment Criteria
1. Basic note (must add)
(a) Comments for Class (interface)
(b) Comment of the constructor
(c) Comment on the method
(d) annotations to global variables
(e) Comment for field/attribute
Note: Simple code to make a simple comment, note content is not more than 10 words, in addition, the persistence of the object or Vo object getter, setter method does not need to comment. Please refer to the following example for specific annotation formats.
2. Special must be annotated (must add)
(a)Typical AlgorithmsMust have a comment.
(b) There must be a comment in the code that is not clear.
(c) Add a comment that modifies the identity at the point of code modification.
(d) Annotate the code that consists of loops and logical branches.
(e) The interfaces provided to others must be annotated in detail.
Note: There are no examples of such annotation formats. The specific annotation format is self-defined, requiring the annotation content to be accurate and concise.


Comment Format
1, single-line (single-line) Comment: "//..."

2. Block comment: "/... /”

3. Documentation notes: "/* ... /”

4. Javadoc annotation Tag syntax

@author description of the class indicates the author of the development of such a module

@version the description of the class indicates the version of the class module

@see a reference to the description of classes, properties, methods, and related topics

Description of a parameter in a method @param description of the method

Description of the method return value @return The description of the method

@exception the description of the method, describe the exceptions that the method might throw

Example of annotations
1. Class (interface) annotations

For example:

/**
* Class description goes here.
* @ClassName: Test
* @author Administrator
* @date 2016/6/29
*
*/

public class Test extends Button {

......

}
2. Construction Method Comments

For example:

public class Test extends Button {
/**
* Constructor description goes here.
* @param name
* The more description.
*
*/
Public Test (String name) {

......

}

}
3. Method Notes

For example

public class Test extends Button {
/**
* Fuction description goes here.
* @param color
* @return void
* @exception (If needed)
* @author Administrator
* @date 2016/6/29
*
*/
Public Voidaddcolor (String color) {

......

}

}
4. global variable Annotations

For example:

Public final class String

Implements Java.io.Serializable, Comparable,charsequence

{

/* The value is used for characterstorage. /
Private final char value[];

/* The offset is the first index of Thestorage, which isused. /
private final int offset;

/* The count is the number ofCharactersin the String. /
private final int count;

/* Cache The hash code for the string/
private int hash; Default to 0

......

}
5. Field/attribute comments

/* CLASSVAR1 documentation Comment /
public static int classVar1;

/** ClassVar2 documentation comment that happens to be
* More than one line long
*/
private static Object classVar2;

/* INSTANCEVAR1 documentation Comment /
Public Object instanceVar1;

/* INSTANCEVAR2 documentation Comment /
protected int instanceVar2;

/* INSTANCEVAR3 documentation Comment /
Private object[] INSTANCEVAR3;


6. File Comments

/*
* @ (#) Blah.java 1.82 99/03/18
*
* Copyright (c) 1994-1999 Sun Microsystems, Inc.
901 San Antonio * Road, Palo Alto, California, 94303, u.s.a.all rights reserved.
*

* This software is the confidential and proprietary information of Sun
* Microsystems, Inc. ("Confidential Information"). You shall not
* Disclose such confidential information and shall use it only in
* accordance with the terms of the license agreement your entered into
* with Sun.
*/

Package Java.blah;

Import Java.blah.blahdy.BlahBlah;

/**
* Class description goes here.
* @version 1.82 1999
* @author Firstname Lastname
*
*/
public class Blah extends SomeClass {
...
}
)

Welcome to the Csdn-markdown editor