Shulou(Shulou.com)06/02 Report--

This article will explain in detail how to use the JavaDoc command for you. The editor thinks it is very practical, so I share it with you as a reference. I hope you can get something after reading this article.

The command line syntax for javadoc is as follows:

Javadoc [options] [packagenames] [sourcefiles] [@ files]

Parameters can be arranged in any order. These parameters and some related contents are described below:

List of Packagenames packages. 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 recursively act on subpackages, you are not allowed to use wildcards for package names; you must explicitly list each package you want to document.

List of Sourcefiles source files. This option can be a series of source file names (separated by spaces) and wildcards can be used. Javadoc allows four kinds of source files: class source code files, package description files, overall overview files, and other miscellaneous files.

◇ class source code file: the source code file for a 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", placed with the package's .java file. The contents of the package description file are usually documents written using HTML tags. When javadoc executes, it automatically looks for the package description file. If found, javadoc will first process the contents between the description files, then put the results into the Package Summary page of the package, and finally put the first sentence of the package description file (immediately) on the output Overview summary page, and precede the statement with the package name of the package.

◇ general overview file: javadoc can create a general overview file that describes the entire application or all packages. The overall overview file can be named or placed anywhere. The-overview option indicates the path and name of the overall overview file. The contents of the general overview file are documents written using HTML tags. When javadoc executes, if it finds the-overview option, it will first process the contents between files; then put the processed results at the bottom of the output Overview summary page; and finally put the first sentence in the overall overview file at the top of the output Overview summary page.

◇ other miscellaneous files: these files usually refer to some picture files, Java source code files (.java), Java programs (.class), Java Mini Program (Applets), and HTML files related to the HTML files output by javadoc. These files must be placed in the doc-files directory. Each package can have its own doc-files directory. For example, you want to use an image of a button (Button.gif) in the HTML document of java.awt.Button. First, you must put the picture file in C:usersrcjavaawtdoc-files; then add the following comments to the Button.java file

/ * *

* This button looks like this:

, /

@ files includes the file. To simplify the javadoc command, you can put the file name and package name of the document you need to create 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 called mypackage.txt with the following contents:

Com.mypackage1

Com.mypackage2

Com.mypackage3

Then execute the following command:

Javadoc-d apidoc @ mypackage.txt

Options command line options. Javadoc uses doclets (doclets is a program written in doclet API. To determine the content and format of the output Some of the command line options are common options available for all doclet, and some are specialized options provided by the default standard doclet. Here are some of their commonly used options:

General options:

◇-1.1 generates documents that have the appearance and functionality of documents generated by javadoc version 1.1. Not all options are available for the-1.1 option, which can be viewed 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.*, etc.).

◇-sourcepath sourcepathlist specifies the source file search path for the package. It is important to note, however, that the-sourcepath option can only be used if the package name is specified in the javadoc command. If you specify a package name and omit-sourcepath, javadoc uses the classpath to find the source file. Example: suppose you plan to create a document for com.mypackage, and the source file is located in C:usersrc. Then you can use the following command:

Javadoc-sourcepath c:usersrc com.mypackage

◇-classpath classpathlist specifies the path where javadoc looks for "reference classes". Reference classes are documented classes plus any classes they reference. Javadoc searches all subdirectories of the specified path. Classpathlist can contain multiple paths (use; separate). If-classpath is omitted, javadoc uses-sourcepath to find source and class files. Example: suppose you plan to create documentation for com.mypackage, the location of the source file is C:usersrc, and the package depends on the libraries in C:userlib. Then you can use the following command:

Javadoc-classpath c:userlib-sourcepath c:usersrc com.mypackage

◇-overview pathfilename tells javadoc to get the overview document from the file specified by pathfilename and put it in the output overview page (overview-summary.html). Where pathfilename is the relative path relative to-sourcepath.

◇-public displays only public classes and members.

◇-protected displays only protected and public classes and members. The default option.

◇-package displays only packages, protected and public classes, and members.

◇-private displays all classes and members.

◇-doclet class specifies the custom doclet class that javadoc produces the output. If you omit this option, javadoc will generate a series of HTML documents using the default doclet.

◇-docletpath classpathlist is related to the-doclet option, which defines the path to the custom doclet class file. Classpathlist can contain multiple paths (with; separate).

◇-verbose provides more detailed information when javadoc is running.

Standard doclet specific options:

◇-author includes the "author" entry in the generated document.

◇-d directory specifies the directory where javadoc saves the generated HTML files. Omitting this option will save the file in the current directory. Directory can be an absolute directory or a relative directory relative to the current directory.

◇-version includes a "version" entry in the generated document.

◇-use generates "use" pages for classes and packages. These pages describe how the class and packages are used in the files involved in the javadoc command. For example, for a given class C, the usage page of C will contain a subclass of C, a field of type C, a method that returns a variable of type C, and a method and constructor with a variable type of C in the parameters.

◇-splitindex divides index files into multiple files in alphabetical order. Each file corresponds to a letter.

◇-windowtitle title specifies the title of the output HTML document.

◇-header header specifies the header text of the output HTML document.

◇-footer footer specifies the footnote text of the output HTML document.

◇-bottom text specifies the text at the bottom of the output HTML document.

◇-group groupheading packagepatten;packagepatten;... Separate packages as specified by the command on the overall overview page. 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

You will have the following results 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 help links in the navigation bar of the file.

◇-helpfile pathfilename specifies the help file that the help link in the navigation bar points to. Ignore this option and javadoc will generate the default help file.

◇-stylesheetfile pathfilename specifies the path to the HTML stylesheet file for javadoc. Ignore this option and javadoc will automatically generate a stylesheet file, stylesheet.css.

JavaDoc document markup

Javadoc comments start with "/ *" and end with "* /", which can contain plain text, HTML tags, and javadoc tags. Javadoc only handles comments in the source file before class / interface definitions, methods, fields, and constructors, ignoring comments located elsewhere. Examples are as follows:

/ * *

* Demo--Helloworld

* @ author sunjl

* @ version 1.0 2001-10-15

, /

Public class myHelloworld

{

/ * *

* display string used in the main () method

* @ see # main (java.lang.String [])

, /

Static String SDisplay

/ * *

* display HelloWorld

* @ param args string brought from the command line

* @ return none

, /

Public static void main (String args [])

{

SDisplay = "Hello World"

System.out.println (SDisplay)

}

}

Use the following command:

Javadoc-private-d doc-author-version myHelloworld.java

You can then generate beautiful API documents about myHelloworld.java.

The tag that starts with @ in the above example is the javadoc tag. The correct use of javadoc tags in Java programs is a good annotation habit and will be very helpful for javadoc to automatically generate complete formatted API documents from source code files. The various tags are described in detail below.

◇ @ author name-text specifies the "author" entry in the generated document, introduced from JDK/SDK 1.0. Name-text can specify multiple names (separated by ","). Documentation comments can contain multiple classes.

◇ {@ docroot} represents the root path where the document was generated, introduced since JDK/SDK 1.3. Examples of usage are as follows

/ * *

* see the copyright

, /

Assuming that the root directory of the generated document is doc, and the last file generated by the file in which the comments above are located is docutilityutl.html, then the link to "copyright" points to. Copyright.html.

◇ @ deprecated deprecated-text adds a comment indicating that the API is not recommended.

A synonymous tag for ◇ @ exception class-name description @ throw, introduced since JDK/SDK 1.0.

◇ {@ link package.class#member label} inserts an inline link to package.class#member, introduced since JDK/SDK 1.2. As an example, assume that the following documents are included in the comments:

/ * Use the {@ link # getComponentAt (int, int) getComponentAt} method. , /

Then the final HTML page generated by javadoc will have the following content

Use the getComponentAt method.

◇ @ param parameter-name description description parameter, introduced since JDK/SDK 1. 0.

◇ @ return description describes the return value, introduced since JDK/SDK 1. 0.

◇ @ see reference adds the title "see" with links or text items to reference, introduced since JDK/SDK 1.0. The @ see tag has three forms, which are described below:

(1) @ see "string" adds a text entry to "string" without generating a link.

(2) @ see Label uses 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 for annotations for default serializable domains, introduced since JDK/SDK 1.2.

◇ @ serialField field-name field-type field-description establishes documentation for the ObjectStreamField component of the serialPersistentFields member of the Serializable class, introduced from JDK/SDK 1.2.

◇ @ serialData data-description data-description establishes documentation of data sequences and types, introduced since JDK/SDK 1.2.

◇ @ since since-text leverages since-text content to add "since" titles to the document, starting with JDK/SDK 1.1.

◇ @ throws class-name description is synonymous with @ exception. Use class-name and description to add "throw" titles to the output document, starting with JDK/SDK 1.2.

◇ @ version version-text adds the title "copyright", which is introduced since JDK/SDK 1.0.

All the tags provided by the standard doclet are described above. However, it is important to note that the use of these tags is location-limited. The tags that can appear in class or interface documentation comments are: @ see, {@ link}, @ since, @ deprecated, @ author, @ version. The tags that can appear in method or constructor documentation comments are: @ see, {@ link}, @ since, @ deprecated, @ param, @ return, @ throws, @ exception, @ serialData. Some of the things that can appear in domain documentation comments are: @ see, {@ link}, @ since, @ desprecated, @ serial, @ serialField.

In addition to the standard tags provided by javadoc itself, can we customize our own tags? Yes, of course. You only need to expand the doclet program of the javadoc standard. In fact, with the doclet API provided by javadoc, you can not only extend the doclet tags, but even change the entire output of the javadoc. To meet your needs, you can make javadoc output plain text, XML files, and so on. Because the extension of doclet involves Java programming, this article will not introduce it in depth.

In summary, javadoc provides complete canonical API documentation capabilities. In software project management, rational use of javadoc can not only reduce the workload of documentation and improve efficiency, but also be very conducive to future software modification and maintenance.

JavaDoc Writing Standard:

1. File Header Comments: each file should be marked with a header, including file name, modification history, copyright information and additional information. For example:

/ * *

* @ (#) demo.java 1.00 2002-05-27

*

* Copyright (c) 2000-2002 China Ping an Insurance Co., Ltd. All rights reserved

* Ping An Insurance Company of China. All rights reserved.

* This software is the confidential and proprietary

* information of Ping An Insurance Company of China.

* ("Confidential Information") You shall not disclose

* such Confidential Information and shall use it only

* in accordance with the terms of the contract agreement

* you entered into with Ping An.

, /

2. Class description: class information, which generally describes the function and implementation of the class.

/ * * class description

, /

3. Variable Description: describe the meaning of variables and the meaning of values.

/ * * var variable description

, /

4. Method Description: indicate the input and output parameters and return value types of each method, and explain the meaning of the value of a special variable. Links to related class documentation.

/ * * method description

* @ param var signification

* @ exception exception class name

* @ return return_value return signification

, /

5. Association Description: document description of the associated class. Where you need to refer to other document descriptions in the comments, you can insert the following in the corresponding comments:

/ * * method description

* @ param var signification

* @ exception exception class name

* @ return return_value return signification

* @ see package.class#member label

, /

6. Package description file: generally describe the function and design outline of the package. Create a description file for each package, named package.html, along with the package's java file.

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.

This is the end of this article on "how to use JavaDoc commands". I hope the above content can be of some help to you, so that you can learn more knowledge. if you think the article is good, please share it for more people to see.

Welcome to subscribe "Shulou Technology Information " to get latest news, interesting things and hot topics in the IT industry, and controls the hottest and latest Internet news, technology news and IT industry trends.