javadoc — The Java API Documentation Generator
CONTENTS
Reference Guide
SYNOPSIS
Arguments can be in any order. See processing of Source Files for details on how the Javadoc tool determines which » .java » files to process.
options Command-line options, as specified in this document. To see a typical use of javadoc options, see Real-World Example. packagenames A series of names of packages, separated by spaces, such as java.lang java.lang.reflect java.awt . You must separately specify each package you want to document. Wildcards are not allowed; use -subpackages for recursion. The Javadoc tool uses -sourcepath to look for these package names. See Example — Documenting One or More Packages sourcefilenames A series of source file names, separated by spaces, each of which can begin with a path and contain a wildcard such as asterisk (*). The Javadoc tool will process every file whose name ends with «.java», and whose name, when stripped of that suffix, is actually a legal class name (see information about Identifiers in the Java Language Specification). Therefore, you can name files with dashes (such as X-Buffer ), or other illegal characters, to prevent them from being documented. This is useful for test files and template files The path that precedes the source file name determines where javadoc will look for the file. (The Javadoc tool does not use -sourcepath to look for these source file names.) Relative paths are relative to the current directory, so passing in Button.java is identical to ./Button.java . A source file name with an absolute path and a wildcard, for example, is /home/src/java/awt/Graphics*.java . See Example — Documenting One or More Classes. You can also mix packagenames and sourcefilenames, as in Example — Documenting Both Packages and Classes -subpackages pkg1:pkg2. Generates documentation from source files in the specified packages and recursively in their subpackages. An alternative to supplying packagenames or sourcefilenames. @argfiles One or more files that contain a list of Javadoc options, packagenames and sourcefilenames in any order. Wildcards (*) and -J options are not allowed in these files. One or more files that contain any of the previous arguments in any order. —>
DESCRIPTION
You can run the Javadoc tool on entire packages, individual source files, or both. When documenting entire packages, you can either use -subpackages for traversing recursively down from a top-level directory, or pass in an explicit list of package names. When documenting individual source files, you pass in a list of source ( .java ) filenames. Examples are given at the end of this document. How Javadoc processes source files is covered next.
Conformance
The standard doclet does not validate the content of documentation comments for conformance nor does it attempt to correct any errors in documentation comments. Be aware of the problems that may arise when generating non-conforming output or output containing executable content, such as JavaScript, when running the javadoc command. The standard doclet does provide the -Xdoclint option to help you detect common problems in documentation comments; however, it is also recommended to check the generated output with any appropriate conformance and checking tools.
For more information about conformance requirements for HTML5 documents, see Conformance requirements in the HTML5 specification. For more information about security issues related to web pages, see Open Web Application Security Project (OWASP).
Processing of source files
Processing of links — During a run, the Javadoc tool automatically adds cross-reference links to package, class and member names that are being documented as part of that run. Links appear in several places:
- Declarations (return types, argument types, field types)
- «See Also» sections generated from @see tags
- In-line text generated from tags
- Exception names generated from @throws tags
- «Specified by» links to members in interfaces and «Overrides» links to members in classes
- Summary tables listing packages, classes and members
- Package and class inheritance trees
- The index
You can add hyperlinks to existing text for classes not included on the command line (but generated separately) by way of the -link and -linkoffline options.
Other processing details — The Javadoc tool produces one complete document each time it is run; it cannot do incremental builds — that is, it cannot modify or directly incorporate results from previous runs of the Javadoc tool. However, it can link to results from other runs, as just mentioned.
As implemented, the Javadoc tool requires and relies on the java compiler to do its job. The Javadoc tool calls part of javac to compile the declarations, ignoring the member implementation. It builds a rich internal representation of the classes, including the class hierarchy, and «use» relationships, then generates the HTML from that. The Javadoc tool also picks up user-supplied documentation from documentation comments in the source code.
In fact, the Javadoc tool will run on .java source files that are pure stub files with no method bodies. This means you can write documentation comments and run the Javadoc tool in the earliest stages of design while creating the API, before writing the implementation.
Relying on the compiler ensures that the HTML output corresponds exactly with the actual implementation, which may rely on implicit, rather than explicit, source code. For example, the Javadoc tool documents default constructors ( see the Java Language Specification) that are present in the .class files but not in the source code.
In many cases, the Javadoc tool allows you to generate documentation for source files whose code is incomplete or erroneous. This is a benefit that enables you to generate documentation before all debugging and troubleshooting is done. For example, according to the Java Language Specification, a class that contains an abstract method should itself be declared abstract. The Javadoc tool does not check for this, and would proceed without a warning, whereas the javac compiler stops on this error. The Javadoc tool does do some primitive checking of doc comments. Use the DocCheck doclet to check the doc comments more thoroughly.
When the Javadoc tool builds its internal structure for the documentation, it loads all referenced classes. Because of this, the Javadoc tool must be able to find all referenced classes, whether bootstrap classes, extensions, or user classes. For more about this, see How Classes Are Found. Generally speaking, classes you create must either be loaded as an extension or in the Javadoc tool’s class path.
Javadoc Doclets
Related Documentation and Doclets
- Javadoc Enhancements for details about improvements added in Javadoc.
- Javadoc FAQ for answers to common questions, information about Javadoc-related tools, and workarounds for bugs.
- How to Write Doc Comments for Javadoc for more information about Sun conventions for writing documentation comments.
- Requirements for Writing API Specifications — Standard requirements used when writing the Java SE Platform Specification. It can be useful whether you are writing API specifications in source file documentation comments or in other formats. It covers requirements for packages, classes, interfaces, fields and methods to satisfy testable assertions.
- Documentation Comment Specification — The original specification on documentation comments, Chapter 18, Documentation Comments, in the Java Language Specification, First Edition, by James Gosling, Bill Joy, and Guy Steele. (This chapter was removed from the second edition.)
Terminology
name A name of a program element written in the Java Language — that is, the name of a package, class, interface, field, constructor or method. A name can be fully-qualified, such as java.lang.String.equals(java.lang.Object) , or partially-qualified, such as equals(Object) .
documented classes The classes and interfaces for which detailed documentation is generated during a javadoc run. To be documented, the source files must be available, their source filenames or package names must be passed into the javadoc command, and they must not be filtered out by their access modifier (public, protected, package-private or private). We also refer to these as the classes included in the javadoc output, or the included classes.
included classes Classes and interfaces whose details are documented during a run of the Javadoc tool. Same as documented classes.
excluded classes Classes and interfaces whose details are not documented during a run of the Javadoc tool.
referenced classes The classes and interfaces that are explicitly referred to in the definition (implementation) or doc comments of the documented classes and interfaces. Examples of references include return type, parameter type, cast type, extended class, implemented interface, imported classes, classes used in method bodies, @see, <@link>, <@linkplain>, and <@inheritDoc>tags. (Notice this definition has changed since 1.3.) When the Javadoc tool is run, it should load into memory all of the referenced classes in javadoc’s bootclasspath and classpath. (The Javadoc tool prints a «Class not found» warning for referenced classes not found.) The Javadoc tool can derive enough information from the .class files to determine their existence and the fully-qualified names of their members.
external referenced classes The referenced classes whose documentation is not being generated during a javadoc run. In other words, these classes are not passed into the Javadoc tool on the command line. Links in the generated documentation to those classes are said to be external references or external links. For example, if you run the Javadoc tool on only the java.awt package, then any class in java.lang , such as Object , is an external referenced class. External referenced classes can be linked to using the -link and -linkoffline options. An important property of an external referenced class is that its source comments are normally not available to the Javadoc run. In this case, these comments cannot be inherited.
SOURCE FILES
Class Source Code Files
Package Comment Files
To create a package comment file, you have a choice of two files to place your comments:
- package-info.java — Can contain a package declaration, package annotations, package comments and Javadoc tags. This file is generally preferred over package.html.
- package.html — Can contain only package comments and Javadoc tags, no package annotations.
A package may have a single package.html file or a single package-info.java file but not both. Place either file in the package directory in the source tree along with your .java files.
package-info.java This file can contain a package comment of the following structure — the comment is placed before the package declaration:
Note that while the comment separators /** and /* must be present, the leading asterisks on the intermediate lines can be omitted. package.html — This file can contain a package comment of the following structure — the comment is placed in the element:
Notice this is just a normal HTML file and does not include a package declaration. The content of the package comment file is written in HTML, like all other comments, with one exception: The documentation comment should not include the comment separators /** and */ or leading asterisks. When writing the comment, you should make the first sentence a summary about the package, and not put a title or any other text between and the first sentence. You can include package tags; as with any documentation comment, all block tags must appear after the main description. If you add a @see tag in a package comment file, it must have a fully-qualified name. For more details, see the example of package.html .
Processing of package comment file — When the Javadoc tool runs, it will automatically look for the package comment file; if found, the Javadoc tool does the following:
Источник
What is JavaDoc tool and how to use it?
JavaDoc tool is a document generator tool in Java programming language for generating standard documentation in HTML format. It generates API documentation. It parses the declarations ad documentation in a set of source file describing classes, methods, constructors, and fields.
Before using JavaDoc tool, you must include JavaDoc comments /**………………..*/ providing information about classes, methods, and constructors, etc. For creating a good and understandable document API for any java file you must write better comments for every class, method, constructor.
The JavaDoc comments is different from the normal comments because of the extra asterisk at the beginning of the comment. It may contain the HTML tags as well.
By writing a number of comments, it does not affect the performance of the Java program as all the comments are removed at compile time.
JavaDoc Format: –
It has two parts: – a description which is followed by block tags.
Some Integrated Development Environments (IDE) automatically generate the JavaDoc file like NetBeans, IntelliJ IDEA, Eclipse, etc.
Generation of JavaDoc: –
To create a JavaDoc you do not need to compile the java file. To create the Java documentation API, you need to write Javadoc followed by file name.
After successful execution of the above command, a number of HTML files will be created, open the file named index to see all the information about classes.
JavaDoc Tags
| Tag | Parameter | Description |
|---|---|---|
| @author | author_name | Describes an author |
| @param | description | provide information about method parameter or the input it takes |
| @see | reference | generate a link to other element of the document |
| @version | version-name | provide version of the class, interface or enum. |
| @return | description | provide the return value |
To generate JavaDoc in Eclipse: –
- Select “Generate JavaDoc” option from Project menu and a wizard will appear.
- Specify the location for the JavaDoc file on your computer, by default it will be in the C drive.
- Select the project and then the packages for which you want to create the JavaDoc file.
- After this on the right side, select the classes for which you want to generate the JavaDoc, by default all the classes will be selected.
- Then you can also specify for which classes the JavaDoc will be generated by selecting the visibility.
- Select the destination location where the generated JavaDoc will be placed.
- Then click Next or Finish.
If you select Next in the next window you can select the Document title and other basic options.
Источник
