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 1. @see's use 2. Use @ Author, @ version Description Class 3. Use @ param, @ Return and @Exception Description Method. 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, 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 identities has been used, and the definition of identity has been placed.
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 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 called "source file name .java" File, and store 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. II. Format document annotation of document annotations can be used to illustrate classes, attributes, methods, etc. In addition to the need to use / ** ... * / limit, you need to pay attention to some detail issues inside. 1. Formatting the 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 writing comments. For example, when you need a wrap, it is not knocked into a back-end, 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 second line. This is think third line. * / Compile output HTML source code is
ThiS Second Line. This is IS secret line. The leading * allows for multiple, the effect is used continuously, and the effect is the same, but there is no other character separation before multiple * numbers, otherwise the separator and The following * 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 annotations in the previous 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 document will generate the correct document for the correct document. However, only the position of the two lines is needed, become an error, will be wrong: / ** Commnet for class * / import java.lang. *; Public class test {...} // An example of an error This example exchanges the above-instant IMPORT statement and the document comment portion, but the result is not the same - the contents of the above comments are not found in the generated document. 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. The three parts of the document comment are divided into three parts according to the effects shown in the document. Example first is as follows.
/ ** * Show method brief description. * SHOW method Detailed description of the first line * Show method Detailed description of the second line * @Param b True Representation display, False indicates hidden * @returN no return value * / public void show (boolean b) {frame.show (b);} The first part is briefly described. 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. The part is selected by the red frame as the picture below: The brief description is written in front of a document annotation (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 part to the next paragraph, as described in the first line of the * Show method .... " In addition to this, we can also use it. 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 shows the location in the document as shown below: This part of the document in the previous example is: * Show method brief description. * SHOW method Detailed description of the first line * Show method Detailed description of the second line ? 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: Part III corresponding code in the previous example is * @Param B true representation, false means hidden * @return no return value except @param and @return, there are other special specials Mark, used for instructions for classes, attributes, and methods, respectively ... don't push me, I will say it right away. III. Using the Javadoc tag Javadoc tag is a special tag inserted into a 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. 1. @see's Using @see has three: @see class name @see # method name or attribute name @see class name # method name or attribute name class name, you can only write a class name (such as String) as needed Or write a full name (such as java.lang.string). 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 []) can sometimes be lazy: If in the above example, there is no count this property, then the reference method count () can be short-handed 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 related parts of the {} generated are as follows: String and StringBuffer are in the java.lang package, because this package is imported by default, these two classes can write class names, 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. Using @ Author, @ Version Description Class The two tags 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's name @Version version of which, @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 * @vesis version 2.00 * / public class testjavadoc {} Related section of the generation document is shown in the figure: From the illustration of the generated document, two @ The Author statement is 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, combined two @Version statements as a sentence: @Author fancybird @version version 1.00Version 2.00 results are as follows: We do this to achieve the goal, no destruction rule. The version number after the author name and @version after @Author can be any HTML format that the user is defined, so we can use the tag to display its branch. At the same time, in a @version specifies two separate version numbers, 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 Experience Class Name Description Each @PARAM can only describe a parameter of the method, so if the method requires multiple parameters, you need to use @param multiple times. To describe it. 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 na 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: returnaf; }} The document related to generated by Javadoc is as follows: It can be seen, in the upper example is except that the @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. The javadoc command runs javadoc -help to see Javadoc usage, the common parameters are listed here: Usage: javadoc [options] [PackageNames] [SourceFiles] Options: -public only display PUBLIC class and member -Protace display protected / public class And members (default) -Package display package / protected / public class and member -Private Show all classes and members -D
The target directory of the output file -Version contains the @Version segment -author contains @Author segment -splitIndex to divide the index into one file corresponding to each letter - WindowTitle
Document browser window Title Javadoc compiles documentation, you can give a list, or give a list of source file 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 Javadoc command: javadoc fancy / test.java fancy / eCommand.java fancy / editor / edocument.java fancy / editor / eview.java is given Java Source files as a method of compiling parameters, note that the file path should be changed according to the actual situation. It is also possible to give the package name as a compilation parameter, such as the Javadoc Fancy Fancy.editor opens the index.html file generated by the browser to find the different ways of compiling the results, as shown below: By the second command is generated Documents are 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)
