The command line Syntax of javadoc is as follows:
Javadoc [options] [packagenames] [sourcefiles] [@ files]
Parameters can be arranged in any order. The following describes these parameters and related content:
• Packagenames package list. This option can be a series of Package Names (separated by spaces), such as java. lang java. lang. reflect java. awt. However, because javadoc does not apply recursively to sub-packages and does not allow wildcards to be used for package names, you must list each package in the document you want to create.
• Sourcefiles source file list. This option can be a series of source file names (separated by spaces), and wildcards can be used. Javadoc allows four source files: class source code files, package description files, general overview files, and other miscellaneous files.
◇ Class source code file: source code file of the class or interface.
◇ Package description file: Each package can have its own package description file. The name of the package description file must be "package.html", which is placed together with the. java file of the package. The content of the package description file is usually written in HTML. During javadoc execution, the package description file is automatically searched. If it is found, javadoc will first process the content between the <body> </body> In the description file, and then put the processing result on the Package Summary page of the Package, finally, place the first sentence of the package description file (close to <body>) in the output Overview summary page, and add the package name before the statement.
◇ Overview file: javadoc can create a general overview file to describe the entire application or all packages. The overview file can be named or placed in any location. -The overview option indicates the path and name of the overall overview file. The content of the overview file is a document written with HTML tags. If the-overview option is found during javadoc execution, it will first process the content between <body> </body> in the file; then, place the processed result to the bottom of the output Overview summary page. Finally, place the first sentence in the overall summary file to the top of the output Overview summary page.
◇ Other miscellaneous files: these files are usually image files related to HTML files output by javadoc, Java source code files (. java), Java program (. class), Java Applet (Applets), HTML files. These files must be stored in the doc-files directory. Each package can have its own doc-files directory. For example, you may want to use a pay-as-you-go image (button.gif) in the HTML file of java.awt.button ). First, you must put the image file in C: usersrcjavaawtdoc-files. Then add the following annotations to the Button. java file.
• @ Files contains files. To simplify the javadoc command, you can put the file name and package name of the document to be created in one or more text files. For example, to simplify the following command:
Javadoc-d apidoc com. mypackage1 com. mypackage2 com. mypackage3
You can create a file named mypackage.txt with the following content:
Com. mypackage1
Com. mypackage2
Com. mypackage3
Run the following command:
Javadoc-d apidoc @mypackage.txt
• Options command line options. Javadoc uses doclets (doclets is a program written using the doclet API .) To determine the output content and format. Some of the command line options are common options available for all doclets, and some are dedicated options provided by the default standard doclet. The following describes some common options:
General options:
◇-1.1 generate documents with the appearance and functions of documents generated by javadoc 1.1. Not all options can be used for the-1.1 option. You can view them using javadoc-1.1-help.
◇-Help displays online help.
◇-Bootclasspath classpathlist specifies the "root class" (usually some classes that come with the Java platform. For example, java. awt.
◇-Sourcepath sourcepathlist specifies the source file search path of the package. Note that the-sourcepath option can be used only when the package name is specified in the javadoc command. If the package name is specified but-sourcepath is omitted, javadoc uses the class path to find the source file. Example: assume that you want to create a document for com. mypackage. The source file is in C: usersrc. Then you can use the following command:
Javadoc-sourcepath c: usersrc com. mypackage
◇-Classpath classpathlist specifies the javadoc path for "reference class. A reference class is a class with documents plus any class they reference. Javadoc searches all subdirectories in the specified path. Classpathlist can contain multiple paths (separated by commas ). If-classpath is omitted, javadoc uses-sourcepath to find the source file and class file. Example: assume that you intend to create a document for com. mypackage. The source file is C: usersrc, and the package depends on the library in C: userlib. You can use the following command:
Javadoc-classpath c: userlib-sourcepath c: usersrc com. mypackage
◇-Overview pathfilename succeeded. Pathfilename is the relative path relative to-sourcepath.
◇-Public: Only public classes and members are displayed.
◇-Protected only displays protected and public classes and members. Default options.
◇-Package only displays packages, protected and public classes, and members.
◇-Private: displays all classes and members.
◇-Doclet class specifies the custom doclet class in which javadoc generates output content. If this option is ignored, javadoc uses the default doclet to generate a series of HTML documents.
◇-Docletpath classpathlist is related to the-doclet option and specifies the path of the custom doclet class file. Classpathlist can contain multiple paths (separated by commas ).
◇-Verbose provides more detailed information during javadoc operation.
Standard doclet special options:
◇-Author contains the "author" item in the generated document.
◇-D directory specifies the directory where javadoc saves the generated HTML file. If this option is omitted, the file is saved in the current directory. Directory can be an absolute Directory or a relative Directory relative to the current Directory.
◇-Version contains the "version" item in the generated document.
◇-Use generates the "use" page for classes and packages. These pages describe the usage of the class and package in the files involved in the javadoc command. For example, for a given class C, the usage page of class C will contain the subclass of class C, the domain of type C, return the method with the variable type C and the method and constructor with the variable type C in the parameter.
◇-Splitindex divides index files into multiple files alphabetically. Each file corresponds to a letter.
◇-Windowtitle title: Specifies the title of the output HTML document.
◇-Header specifies the header Text of the output HTML document.
◇-Footer specifies the footer Text of the output HTML document.
◇-Bottom text specifies the text at the bottom of the output HTML document.
◇-Group groupheading packagepatten ;... On the overview page, separate packages as specified by the command. For example, execute the following command:
Javadoc-group "Core Packages" "java. lang *: java. util"
-Group "Extension Packages" "javax .*"
Java. lang java. lang. reflect java. util javax. servlet java. new
The following results will be displayed on the page:
Core Packages
Java. lang
Java. lang. reflect
Java. util
Extension Packages
Javax. servlet
Other Packages
Java. new
◇-Noindex does not output index files.
◇-Help ignores the help link in the navigation bar of the file.
◇-Helpfile pathfilename specifies the help file to which the help link in the navigation bar points. Ignore this option. javadoc generates the default help file.
◇-Stylesheetfile pathfilename specifies the path of the HTML style table file of javadoc. If you skip this step, javadocwill automatically create a sample table file, stylesheet.css.
JavaDoc document mark
The javadoc annotation ends with "", which can contain common text, HTML tag, and javadoc tag. Javadoc only processes comments in the source file before class/interface definitions, methods, fields, and constructors, and ignores Comments located elsewhere. Example:
Public class myHelloworld
{
Static String SDisplay;
Public static void main (String args [])
{
SDisplay = "Hello World ";
System. out. println (SDisplay );
}
}
Run the following command:
Javadoc-private-d doc-author-version myHelloworld. java
You can generate beautiful API documentation on myHelloworld. java.
In the above example, the tag starting with @ is the javadoc tag. Correct use of javadoc tag in Java programs is a good habit of commenting. It will be very helpful for javadoc to automatically generate a complete format API document from the source code file. The following describes various tags in detail.
◇ @ Author name-text specifies the "author" item in the generated document, which is introduced from JDK/SDK 1.0. Name-text can specify multiple names (separated ). Document annotations can contain multiple classes.
◇ {@ Docroot} indicates the root path of the generated document, which is introduced from JDK/SDK 1.3. Example
The root directory of the hypothetical generation file is doc2. the final file generated after the annotation is doccutilityutl.html. Then, the "copyright" link is directed to ..copyright.html.
◇ @ Deprecated-text to add comments, indicating that this API is not recommended.
◇ @ Exception class-name description @ throw is introduced from JDK/SDK 1.0.
◇ {@ Link package. class # member label} inserts an embedded link pointing to package. class # member, which is introduced from JDK/SDK 1.2. For example, it is assumed that the annotation contains the following documents:
The final HTML page generated by javadoc contains the following content:
Use the <a href = "Component.html # getComponentAt (int, int)"> getComponentAt </a> method.
◇ @ Param parameter-name description parameter, which is introduced from JDK/SDK 1.0.
◇ @ Return description the return value, which is introduced from JDK/SDK 1.0.
◇ @ See reference Add "see" title, which contains links or text items pointing to the reference, which is introduced from JDK/SDK 1.0. The @ see tag has three forms:
(1) @ see "string" adds text items for "string" without generating links.
(2) @ see <a href = "URL # Value"> Label </a> Use HTML tags to generate links
(3) @ see package. class # member Label uses the Java language name package. class # member to generate links.
◇ @ Serial field-description is used to annotate the serializable domain by default, which is introduced from JDK/SDK 1.2.
◇ @ SerialField field-name field-type field-description This document describes how to create the ObjectStreamField component of the serialPersistentFields Member of the Serializable class, which is introduced from JDK/SDK 1.2.
◇ @ SerialData data-description documents for data sequence and type, which will be introduced from JDK/SDK 1.2.
◇ @ Since-text adds the "since" title to the document using the since-text content, which is introduced from JDK/SDK 1.1.
◇ @ Throws class-name description is synonymous with @ exception. Use class-name and description to add a "throw" title to the output document, which is introduced from JDK/SDK 1.2.
◇ @ Version-text add the "Copyright" title, which is introduced from JDK/SDK 1.0.
All the tags provided by the standard doclet are described above. However, note that the use of these tags is location-specific. The annotations in the class or interface document can be marked as @ see, {@ link}, @ since, @ deprecated, @ author, and @ version. Tags that can appear in methods or constructor document comments include: @ see, {@ link}, @ since, @ deprecated, @ param, @ return, @ throws, @ exception, and @ serialData. The annotations in the domain documents include @ see, {@ link}, @ since, @ desprecated, @ serial, and @ serialField.
Apart from the standard tag provided by javadoc, can we customize our own tag? Of course. You only need to expand the doclet program of the javadoc standard. In fact, the doclet API provided by javadoc can not only expand the doclet tag, but also change the entire output of javadoc. To meet your needs, you can use javadoc to output common text and XML files. Since the extension of doclet involves Java programming, this article will not go into depth.
In short, javadoc provides a complete and standardized API documentation function. In software project management, the rational use of javadoc not only reduces the document workload during development and improves efficiency, but also facilitates the modification and maintenance of software in the future.
JavaDoc writing specifications:
1. File Header Comments: each File should be marked with a File Header, including the File name, modification history, copyright information, and additional information. For example:
2. class description: class information, which describes the functions and implementations of a class.
3. Variable Description: describes the meaning and value of a Variable.
4. Method Description: indicates the input, output parameters, and return value types of each Method, indicating the meaning of the values of special variables. Links to related documents.
5. Association Description: Description of the Association class document. The Description of other documents must be referenced in the comments. The Description can be inserted as follows:
6. Package Description file: describes the features and design overview of the package. Create a development file for each package, named package.html, and put it together with the java file of the package.
Note: When javadoc generates a document, the first sentence of the html file is placed in package summary, and the entire content is placed in Overview summary.
Author: wyq_wzw
Start building with 50+ products and up to 12 months usage for Elastic Compute Service
1 on 1 presale consultation
24/7 Technical Support 6 Free Tickets per Quarter Faster Response
Alibaba Cloud offers highly flexible support services tailored to meet your exact needs.
A comprehensive suite of global cloud computing services to power your business
Payment Methods We Support
