Introduction to javadoc command
Chapter 6: Generate Javadoc
This time, it is not an implementation aspect such as Javadoc specifications and writing method, but I would like to focus on how to use and operate the javadoc command. Regarding how to write comments, when I learned books about how to write Javadoc I would like to summarize it.
Javadoc overview
The Javadoc command parses declarations and comments in Java source files and by default public classes, protected classes, nested classes (excluding anonymous inner classes), Implementation documentation for interfaces, constructors, methods, and fields Generate in HTML format.
Javadoc page list
What about Javadoc, the artifact of the javadoc command, to make it easier to explain later? Here's an example of how the page will be generated.
Basic content page
-** Overview page ** (overview-summary.html) Javadoc top page. An overview of the entire unit of API and package set is written. -** Package page ** (package-summary.html) A page that exists for each package. The outline of the package is written. -** Class page / Interface page ** (classname.html) A page that exists for each class and interface. Contains information about the members and methods that belong to the class.
~ Overview page ~
~ Package page ~
~ Class page ~
Cross-reference page
-** Class hierarchy page ** (overview-tree.html) There is one for each Javadoc. The elements to which they belong can be hierarchized and listed. -** Class hierarchy page ** (package-tree.html) There is one for each package. Elements belonging to a package can be hierarchized and listed. -** Specification page ** (package-use.html) You can list the target classes, packages and classes that use the interface. -** Deprecated API page ** (deprecated-list.html) List deprecated (possibly removed in the future) classes, methods, etc. -** Constant Field Values Page ** (constant-values.html) Page for static field values -** Serialized form page ** (serialized-form.html) A page about classes that can be serialized (externalized). -** Index ** (index-*. Html) All classes, interfaces, constructors, fields, and methods, You can list them in alphabetical order.
Support page
--Help page (help-doc.html) It contains a navigation bar and instructions for each page.
HTML frame
The javadoc command creates a couple of HTML frames. If there is one package, a frame for the class will be created on the lower left and a frame for details will be created on the right. If there are multiple packages, a frame for the package will be added in the upper left.
Javadoc command format
#The order in which the javadoc command arguments are specified is arbitrary.
$ javadoc [options] [packagenames | sourcefilenames] [-subpackages pkg1:pkg2:...]
- options
Command line options passed to the javadoc command. - packagenames
The name of the package to be processed. Specify asjava.lang java.awt. You must specify the target package individually and you cannot use wildcards. To specify it recursively, use `` `-subpackages``` described below. - sourcefilenames
The name of the source file to be processed. Each file starts with a path, such as an asterisk (\ *) You can include wildcards. - -subpackages pkg1:pkg2:...
Recursively within the specified package and its subpackages from the source file Generate a document. It is not necessary to specify the package name and source file name.
Specifying the source file
Source file type
There are the following four target files that are parsed when Javadoc is generated.
-** Class file ** A file ending in .java. If the class name is invalid according to Java convention, it will not be processed. Example) Start with a number. "-"including. Such -** Package comment file ** It can be placed for each package and is placed in the same hierarchy as the .java file. Describe the outline of the package. The file name is fixed, and there are the following two specifications. --Before JDK1.5: package.html --JJ1.5 or later: package-info.java -** Summary comment file ** A file for generating an overview page. The file name and location are arbitrary, but usually Make it overview.html and put it at the top level of the source tree. Generated by specifying the summary comment file name with the -overview option. -** Files in the doc-files directory ** For example, you want to insert an image file in Javadoc of a class called Sample class. If you want to use files that deviate from the rules of .java, call doc-files in the same hierarchy as .java. By creating and arranging a directory, the stored file can be analyzed.
How to specify various source files
There are three main ways to specify the source file.
** 1. Specify the package ** Since wildcards cannot be used, separate them with a single-byte space in the following format. Specify all packages individually. The specification must be a complete specification.
java.lang java.lang.reflect java.awt
** 2. Specify the source file path **
Specify the path of the source file. Either absolute path or relative path can be specified,
For a relative path, specify the relative path from the current directory.
Wildcards can be used, and if you specify more than one, separate them with a single-byte space.
#### **`/src/java/awt/Sample.java src/java/awt/*Bar.java`**
** 3. Specify packages recursively with the -subpackages option ** If you specify a package, you can specify the range including subpackages. Wildcards cannot be used. When specifying, separate them with a colon (:) in the following format.
javax.swing
> Normally, individual packages are rarely specified.
Specify the source file path with a wildcard or with the -subpackages option
It is mainly specified recursively.
** Ex. When specifying in the package **
When specifying the source file in the package,
You cannot follow the package hierarchy without specifying the package root.
Therefore, you need to specify the directory that is the starting point of the package.
There are two ways to specify a directory:
--Move the current directory to the starting directory and execute the javadoc command
--Specify the starting directory with the -sourcepath option
## javadoc options
Options that can be passed to the javadoc command include
There are two options: javadoc command options and doclet-provided options.
I won't go into details about docklets,
Think of it as a template that provides the javadoc format.
If you do not explicitly specify a custom doclet, the standard doclet is selected.
### Major options
--- overview <path \ filename>
By specifying the overview.html placed in an arbitrary location with the path, the overview.html is parsed and
Place it on the overview page (overview-summary.html).
For the path, specify the relative path from the directory specified by -sourcepath.
--- d <path>
Output the generated Javadoc to the specified path.
--- source <version>
Specify the source code version. Match the version to that of the compilation.
--1.5: Accepts the code introduced in JDK 1.5. Default value.
--1.4: Accepts code containing assertions introduced in JDK 1.4.
--1.3: Does not support assertions, generics, and other language features introduced since JDK 1.3.
--- classpath <path list>
Specify the path to search for the reference class (.class).
Reference classes are all documented classes, as well as all referenced by those classes.
Includes class. Subdirectories under the specified path will be the search range.
If the classpath is not set, the current directory will be the classpath.
--- sourcepath <path list>
Specify the classpath of the source file. (If you pass packages or -subpackages)
Subdirectories under the specified path will be the search range. With this option,
If -sourcepath is omitted, ** equivalent to classpath ** will be set.
If -classpath is also omitted, ** current directory ** will be set.
--- J <java command options>
Pass options to the runtime system java that runs javadoc. (-J-Xmx32m etc.)
### Specified options to be documented
--- subpackages <Package 1: Package 2 ...>
The generation range can be the specified package and its subpackages and below. (Multiple packages can be specified)
-sourcepath is required when using -subpackages.
--- bootclasspath <path list>
Specify the path where the boot class resides.
### Control system options to be documented
- -public
Show only public classes and members.
- -protected
Show only protected and public classes and members. Default settings.
- -package
Show only package, protected, and public classes and members.
- -private
Show all classes and members.
--- exclude <Package 1: Package 2 ...>
Excludes the specified package and its subpackages from the list specified by -subpackages.
### Docklet options
--- doclet <class>
Specify a docklet other than the standard docklet. Specify the startup class with full specification.
The format for specifying the startup class is `` `-doclet com.example.doclets.SampleDoclet```.
The classpath to the startup class is defined by the -docletpath option.
--- docletpath <classpath 1: classpath 2 ...>
The doclet start class file specified by the -doclet option and the dependent jar files
Specify the path to. The path of the jar file if the start class file is inside the jar file
Only can be specified. You can specify an absolute path or a relative path from the current directory.
This option is not needed if the desired doclet start class is in the search path.
```shell
#SampleDocklet/src/com/example/Suppose it is directly under doclets
-doclet com.example.doclets.SampleDoclet -docletpath /src:/lib/doclet.jar
Debug options
- -verbose
Display detailed messages while running javadoc. If not specified, when loading the source file and when generating the document (per source file), And a message is displayed at the time of sorting (only once in one execution). If specified, detailed information such as the time (in milliseconds) required to parse each Java source file A message is displayed. - -quiet
Suppress messages other than error messages and warning messages.
Internationalization options
---locale
Run
Here, comment and Javadoc generation files are added to the sample code used so far.
The following configuration added is used as sample code.
UseCommons.java
package com.example.app;
import org.apache.commons.lang3.StringUtils;
import com.example.util.StrFactory;
/**
*A class for using Apache Commons.
*/
public class UseCommons {
public static void main(String[] args) {
System.out.println(CommonsHelper.returnNgStrIfHasProbrem(null));
System.out.println(CommonsHelper.returnNgStrIfHasProbrem(""));
StrFactory strFactory = new StrFactory();
System.out.println(CommonsHelper.returnNgStrIfHasProbrem(strFactory.sayHelloWorld()));
}
static class CommonsHelper {
static String returnNgStrIfHasProbrem (String target) {
if (StringUtils.isEmpty(target)) {
return "NG";
} else if (StringUtils.isBlank(target)) {
return "NG";
}
return target;
}
}
}
StrFactory.java
package com.example.util;
/**
*A factory class for generating various strings.
*/
public class StrFactory {
/**
* "Hello World!"Will be returned.
*/
public String sayHelloWorld() {
return "Hello World!";
}
}
package.html
<html>
<body>
This is a sample package comment.
</body>
</html>
overview.html
<html>
<body>
This is a summary comment of the sample.
</body>
</html>
As mentioned above, after preparing the source file, execute the following command.
#The current directory is/java-It is a sample.
$ javadoc -classpath ./src:./lib/commons-lang3-3.10.jar -subpackages com.example -overview ./overview.html -d ./docs
When executed, Javadoc will be generated in / java-sample / docs specified as the output destination.
To see the Javadoc, open index.html.
Below is the actual output.
in conclusion
The sample code doesn't make the minimum necessary comments, Actually use HTML for comments, insert images, refer to external libraries, etc. You can do various things, so read or research specialized books about their implementation. I hope you will study.
Recommended Posts