table of Contents
Foreword I. Java Document and Javadoc II. Document Comments Format 1. Format of Document Note 2. Three parts of the document comment. Use the javadoc tag http://outinn.myrice.com/book/javadoc/#t31 http: //outinn.myrice.com/book/javadoc/#t32 http://outinn.myrice.com/book/javadoc/#t33 4. javadoc command
Foreword
Java's grammar is similar to C , then, do you know how many Java's comments? Two?
// Note One row / * ... * / Notes
Not completely, in addition to the above two, there are third, document comments:
/ ** ...... * / Comment Several lines, and write the Javadoc documentation
Usually, the multi-line of writing of this comment is as follows:
/ ** * ......... * ......... * /
Pause, suspend! What is the use of this third annotation? What is Javadoc?
Ok, let me tell you -
I. Java documentation and javadoc
Java programmers should know that using JDK development, the best help information is from the Java document released by Sun. It is divided into detail, and the classification provides each method, attribute help information, with detailed class tree information, index information, etc., and provides a number of related classes, such as inheritance, implementation, and more.
The Java document is all organized by some HTML files, and they can download their compressed packages on the SUM site. But you can't think of it, we can build themselves. - Only, stop the appetite.
After the JDK is installed, there is a src.jar file or src.zip file in the installation directory, which is compressed in zip format, and WinZip is extracted. After decompression, we can see all the .java files in the separate directory. Yes, these are the source code of Java running class. It is very complete, and even the comments are written in a clear ... However, how do you see these comments a bit like a feeling?
This is not surprising, and our fans will be unveiled. If you compare the document annotation in the .java source file (/ ** ... * /) and the contents of the Java document, you will find that they are the same. The Java document is just a matter of formatting and typography. Again again, you will find that the comments in the .java source file also have an HTML ID, such as ,
, , etc. In the Java document, the place where these identifiers have been identified. The definition has been plated.
Finally, it's a big white, the original Java document is from these comments. No wonder these comments are called document comments! However, what tool turns these comments into documentation?
It should be a time when javadoc is please. In the bin directory of JDK, you can find javadoc, if it is a JDK under Windows, its file name is javadoc.exe. When using Javdoc compiles .java source file, it reads the document comments in the .java source file, and compiles with the Java source program with a certain rule to generate a document.
Before you introduce Javadoc's compilation command, let's take a look at the format of the document comment. However, in order to be able to compile some examples mentioned below, first introduce a javadoc command:
Javadoc -d document storage directory -author -version source file name. Java
This command compiles a Java source file called "Source File Name .java" and stores the generated document in the directory specified by "Document Storage Directory". InDex.html in the generated document is the home page of the document. -author and -Version two options can be omitted.
2. Format of document comments
Document comments can be used to illustrate classes, properties, methods, etc. In addition to the need to use / ** ... * / limit, you need to pay attention to some detail issues inside.
1. Formatting documentation and document comments
The generated document is HTML format, and the identifier of these HTML format is not javadoc, but we write it when you write comments. For example, when you need a wrap, it is not knocked into a carriage return, but writes
, if you want to segment, you should write
before segmentation.
Therefore, format the document is to add a corresponding HTML ID in the document comment.
The text of the document comment is not copied directly to the output file (the HTML file of the document), but after reading each line, delete the front of the predecessor's *, and then enter the document. Such as
/ *** this is first line.
***** this is second line.
is think third line. * /
The HTML source code after compiling and output is
"This is second line.
.
The leading * allows continuous use, its effects are the same as one *, but there is no other character separation before multiple * numbers, otherwise the separator and the * number will be used as the content of the document. The * is here as the left boundary, such as the first line and the second line of the above example; if there is no preamble *, the boundary starts from the first valid character, and does not include the front space, such as the third line of the above example .
It is also necessary to explain that document comments only describe classes, attributes, or methods that followed. Such examples:
/ **** Comment for class * /
Public class test {
/ ***** Comment for a attribute * /
Int number;
/ *** Comment for a Method * /
Public void mymethod () {...}
......
}
Three comments in the above example are document comments on classes, attributes, and methods, respectively. The documents they generate are the classes, attributes, and methods of the next subsequent. The word "immediately" is especially important. If this is ignored, it is likely to cause the generated document error. 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 only need to change the position of the two lines, become an example, it will be wrong:
/ **** Commnet for class * /
Import java.lang. *;
Public class test {......}
// This example is a wrong example
This example only exchanges the above IMPORT statement and document comment portion, but the result is large - generated documentation is not found in the contents of the above comments. What is the reason?
"/ ** commnet for class * /" is a description of the Class Test, put it before "public class test {...}", followed by Class Test, in line with the rules, so generated The document is correct. But after the position and "Import Java.lang. *;" Are changed, it is not Class Test, but an Import statement. Since document comments can only be described, the IMPORT statement is not in this column, so this document comment is omitted as an error. 2. Three parts of document comments
According to the effect shown in the document, the document comment is divided into three parts. Example first is as follows.
/ **
* SHOW method brief description.
Detailed Description *
show a first row a method
* SHOW method detailed description of the second line
* @Param B True Represents display, False is hidden
* @return no return value
* /
Public void show (boolean b) {
Frame.show (b);
}
The first part is briefly. Documentation, for attributes and methods, there is a list before one of the following detailed descriptions. The segment of the property name or method name in the list will be briefed. A portion selected by the red frame in the following figure:
Brief Description Part is written in front of a document annotation, the first point (.) (Including the order). In other words, the document comment is separated by the first point, which is previously briefly, and then the second part and the third portion. As a result of the * Show method in the above example. "
Sometimes, even if it is separated by a bit number, Javadoc will still be wrong, and the part behind the order is also the first part. In order to solve this problem, we can use a
flag to open the second partial portion as the next paragraph, as described in the first line of the "*
show method" in the above example. " In addition to this, we can also use the
to separate.
The second part is a detailed description. This section describes the properties or methods, there is no special requirements in the format, and may contain several points. It is shown in the following figure in the document:
This part of the document is:
* Show method brief description. *
show method detailed in the first line
* Show method
What did you find? Yes, a brief summary is also there. This should be remembered, don't draw a snake! Write a brief summary in the detailed description!
The third part is a special instruction section. This part includes version description, parameter description, return value description, etc. It is in the location of the document:
The third part is the corresponding code in the above example.
* @Param B True Represents display, false indicates hidden * @return no return value
In addition to @Param and @return, there are other special tags, which are used for instructions for classes, attributes, and methods. Don't push me, I will say it right away.
3. Use Javadoc tags
The Javadoc tag is a special tag inserted into the document comment, which is used to identify special references in the code. The Javadoc marker consists of "@" and the marker type and dedicated annotation reference. Remember, three parts - @, tag type, special annotation reference. However, I would rather divide it into two parts: @ and tag types, dedicated annotation references. Although the @ and tag types can sometimes be separated by spaces, I would rather always write them next to the opportunity to reduce the chance.
Javadoc marks are as follows:
Tags for role @author's description indicating that the author @version of the class module indicates that the version of the module is indicated by the version @see to the class, attribute, method, method, reference steering, that is, the related topic @Param pair method Description of the description of a parameter in the method @return's instructions for the method return value @Exception pair method for the method, the method, the possible throwing, the other, the detailed description, the respective markers are described in detail.
Use of @see
There are three syntax of @see:
@see class name @see # method name or attribute name @see class name # method name or attribute name
Class names, you can write only the class name (such as string) or write a full name (such as java.lang.string) as needed. So when I just need to write the class name, when do you need a full name?
If the IMPORT statement in the Java source file contains classes, you can write only the class name, if not included, you need to write a full name. Java.lang has also been included by default. This is the same as the Javac compiles the Java source file, so you can use Javac compilation to determine, Javadoc can be found in Javac in the source program, JavaDoc can also be found; Javac can not find the class, Javadoc can't find, This requires the use of the class.
Method name or attribute name, if it is the property name, only you need to write the name of the property; if it is the method name, you need to write the method name and parameter type, no parameters, you need to write a pair of parentheses. Such as
Member type member name and parameter @see syntax attribute Number @ See number method count () @ See count () method show (boolean b) @see show (boolean) method main (string [] args) @see Main (String [])
Sometimes it can be lazy: If you don't have COUNT, you can be short-write into @see count (). However, for safety, it is better to write all @see count ().
@see's second syntax and third syntax are the reference for the steering method or attribute, what is the difference?
There is no name name in the second syntax, and the default is the current class. So it defines the reference, all of which turides attributes or methods in this class. The class name is pointed out in the third syntax, and it can also be turned to other class properties or methods.
About @see tags, we will give an example. Since @see is the same as the method description, the property description, the method is used, so it is only used as an example.
/ **
* @see string
* @see java.lang.stringbuffer
* @see #str
* @see #str ()
* @see #main (String [])
* @see object # toString ()
* /
Public class testjavadoc {
}
The relevant parts of the generated document are as follows:
String and StringBuffer are in the java.lang package, because this package is imported by default, these two classes can write directly to class, or write a full name. STR, STR () is the same name attributes and methods, so the method name needs to be used () distinguish. Main is a method with parameters, so the parameter type is indicated in (). Tostring () Although there are also (from Object inherited) in this class, we want to refer to the toString () method of the Object class, so use Object # toString (). Surprisingly, why only STR, STR () and main (String []) become a link? It is because the source files of the Java.lang package or Stirng, StringBuffer, and Object are not compiled, so the generated document does not have information about the three classes, and it is not possible to establish a link. Along the next explanation of the Javadoc compile commands will be described in detail.
In the above example, if you go to the STR attribute in the class, what changes will be generated? You will find that it is Str, Str (), and now becomes STR (), STR (), because the Str property is already, STR also represents the method STR ().
2. Use @Author, @ version description class
These two markers are used to specify the author and version of the class. By default, Javadoc is ignored, but the command line switch -author and -Version can modify this feature to make it included in the information. The syntax of these two markers is as follows:
@Author name @version version number
Among them, @ Author can use multiple times to indicate multiple authors, and the comma (,) is separated from each author in the generated document. @Version can also use multiple times, only the first time, the generated document will only display the version number of the @version specified by the @version. Below
/ **
* @Author fancy
* @Author Bird
* @version version 1.00
* @version version 2.00
* /
Public class testjavadoc {
}
The relevant parts of the generation document are as shown:
As can be seen from the illustration of the generated document, both @Author statements are compiled, and the author list is generated in the document. And only the first sentence in two @Version statements was compiled, only one version number was generated.
From the picture, the author list is separated by a comma, if I want the branch what to do? In addition, what should I do if I want to show more than two version numbers?
- We can combine the two @Author statements as a sentence, and combine two @Version statements as a sentence:
@Author fancy
Bird @version version 1.00
Version 2.00
The result is as shown:
We do this to achieve the goal and have no damage rules. The version number after the author name and @version after @author can be any HTML format defined by the user, so we can use the
tag to display its branch. At the same time, in a @Version, two version numbers separated by
, and there is no rules that only display only the first @version content.
3. Use @ param, @ Return and @Exception Description Methods These three tags are only used for methods. @PARAM Description Method, the return value of the @ Return description method, the @ Exception description method may thrown an exception. Their syntax is as follows:
@Param Parameter Name Parameter Description @return Return Value Description @Exception Exception Class Description
Each @PARAM can only describe a parameter of the method, so if the method requires multiple parameters, you need to use @param to describe multiple times.
One @return can only be used in a method. If multiple @return are listed in the document description, Javadoc will issue a warning when it is compiled, and only the first @return is valid in the generated document.
The exception that may be thrown should be described in @Exception. Since a method may throw multiple exceptions, there can be multiple @Exception. Each @Exception should have a briefly detailed anomaly class, indicating that the reason for throwing anomalies should be pointed out. It should be noted that the abnormality class should be determined according to the IMPORT statement of the source file, it is a 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;
}
}
Document related to generated documentation with Javadoc is as follows:
It can be seen that @Param B Excrescent Parameter is redundant, because the parameters are just a N, and there is no B but there is no check when javadoc compiles. Therefore, it is necessary to correctly match the items of the official parameter table in the method when writing document comments. If the parameters in the method parameter table are a, the document gives the interpretation of the parameter X, or more of the parameter i, it will not be able to touch the mind. @EXCEPTIN is also the same.
There is no NullPointRexception in the previous example program, but why do you want to write such a sentence in the document comment? This is not to demonstrate that the excessive exception can be compiled, but to illustrate the possibility of running when the write abnormality is described. In the above example, if the parameter N is a null value (null) given, the program throws a NullPointerexception when running, so the description of NullPointerException is added in the document comment.
There are two @return statements in the above example, but according to rules, in the same method, only the first @return is valid, and the rest will be ignored by JavaDoc. So there is no description of the second @return in the generated document. Tell this, how to write a document comment, you should already be clear, and you will begin to explain the common commands of Javadoc.
Four. Javadoc command
Run Javadoc -help You can see Javadoc usage, where the usual parameters are listed as follows:
Usage: javadoc [options] [packagenames] [SourceFiles]
Option:
-public only displays the PUBLIC class and member -Protected display protected / public class and member (default) -Package display package / protected / public class and member -Private display all classes and members -D
Javadoc can give a list of lists when compiling documents, or give a list of source files. For example, there are two packages in ClassPath 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. So compile (Windows environment) can use the following javadoc command:
Javadoc Fancy / Test.java Fancy / Editor.java Fancy / Editor / ECommand.java Fancy / Editor / Edustrial.java Fancy / Editor / Eview.java
This is a method given as a Java source file as a compilation parameter. Note that the command is the file path, and should be changed according to the actual situation. It is also possible to give the package name as a compilation parameter, such as:
Javadoc Fancy Fancy.editor
Use the browser to open the index.html file that generates the document, you can find the difference in compilation results in two ways, as shown below:
The document generated with the second command is divided into three parts: package list, class list, and class description. After selecting a package in the list list, all classes in the package will be listed; after a class is selected in the class list, the detailed documentation of the class will appear. There are only two parts, class lists, class descriptions, and unparalleled lists with the documents generated in the first command. This is the biggest difference between the two ways to generate documents.
Let's talk about the option.
-public, -Protaced, -Package, -Private four options, only you need to choose one. The extent of their designated display class members. How many members they display are included, as follows:
-Private (Show all classes and members)
-Package (Show package / protected / public classes and members)
-Protacected (Show Protected / PUBLIC Category and Member)
-PUBLIC (only Display public classes and members)
The -d option allows you to define the output directory. If you don't use the -d definition output directory, the generated document file will be placed in the current directory. The use of the -D option is
-d directory name
The directory name is required, that is, if you use the -D parameter, you must specify a directory for it. This directory must already exist. If there is still no existence, create this directory before running Javadoc. -Version and -author are used to control whether to generate @version and @author specified when generating a document. If you do not add these two parameters, you do not include versions and authors in the generated documentation.
The -splitIndex option divides the index into a file corresponding to each letter. By default, only one index file is only one, and all index contents are included. Of course, when the content of the document is not available, this is very suitable, but if the documentation is very much, this index file will contain a lot of content, which is too large. Use -splitIndex to classify the index file by the first letter of each index, each letter corresponds to a file. This way, the burden of an index file is reduced.
-windowtitle option specifies a title to the document, which is displayed on the title bar of the window. If this title is not specified, the default document title is "generated document (no title)". The usage of this option is:
-windowtitle title
The title is a string that does not contain spaces because the space console is used to separate each parameter, so it cannot contain spaces. Similar to -D, if the -windowtitle option is specified, you must specify the title text.
So far, Java documentation and javadoc are over. Javadoc really allows us to do article in Java annotations - generate development documents.
Ayuan
9CBS certified blog expert
Blog expert
Huawei old employees
Big Data
More than ten years, in Huawei, Internet Corporation's experience, profound understanding and practical experience in CRM, big data, mainly sharing various project experience, including architecture, Java, big data and other articles
