Copyright ©2006-2008, Brian Ngure
General Overview
BJavadocTool Overview
BJavadocTool Options
BJavadocTool is a tool for creating javadoc documentation of your JavaTM projects.
General Overview
BJavadocTool helps you to create customized API documentation for your JavaTM projects. This tool allows you to specify standard and advanced documentation generation options through it's user interface. BJavadocTool can be used by any version of the Sun Javadoc utility. Specially formatted Javadoc comments created by you can also be merged into the resulting documentation files. This tool uses almost all of the options specified under the current Sun JDK Javadoc utility (1.5.0_03 as of this writing).
For more information on using the Javadoc utility, please visit Sun's Javadoc home page at http://java.sun.com/j2se/javadoc/index.jsp.
BJavadocTool Overview
You can use BJavadocTool as many times as you want on the classes of your JavaTM projects. Each time, BJavadocTool examines your projects JavaTM source files and regenerates new HTML documentation files.
This tool calls the Javadoc utility specified by you in the "Select Javadoc To Use" dialog box. This enables you to use any version of the Javadoc utility that you wish. To generate Javadoc 1.1 style documentation, select the "Use JDK 1.1 Format" field (described below).
The Javadoc utilty itself uses the Java compiler (javac) to process the source files. Therefore, the source files you want documentation generated for must compile successfully in order for its documentation to be generated.
Note: JavaSoft command line utilities sometimes experience difficulties when processing files which are located in directories whose names include spaces. If you have spaces in your directory names and encounter difficulties with this tool, please remove the spaces in your directory names.
Starting BJavadocTool
- To start BJavadocTool, simply click on the BJavadocTool link in the programs menu or wherever you created the links.
The BJavadocTool GUI will appear:
To begin Javadoc processing, after setting your options, click the OK button. To cancel and close BJavadocTool click Cancel. Clicking the Help button will show this help.
BJavadocTool Options
On the opening screen, are displayed standard javadoc options.
Package(s) Or File(s) To Document
This is where the file(s) or package(s) you want to document are entered. Click the Browse button [...] to select the directory where your .java files reside. This directory will be scanned for .java files. The package names will be obtained from the .java files where available. If your .java file does not have a package structure, the name of the file e.g. "JavaClass1.java" will be added directly to the path of files to document.
You can enter as many package(s) and/or file(s) as you want.
Omit Sub-Packages
In this text field you can specify the sub-packages that should not be documented. Specifying a subpackage in this field instructs Javadoc to exclude processing of any classes in that subpackage.
Output Directory
Here you specify the directory location where the documentation files should be output. Click the Browse button [...] to select a location by browsing the directory tree.
Scope
The selected radio button instructs the Javadoc utility to generate documentation for those classes, variables, methods of a specific visibility. The scopes include:
- public: Shows only public classes and members.
- and protected: Shows only protected and public classes and members. This is the default.
- and package: Shows only package, protected, and public classes and members.
- and private: Shows all classes and members.
The visibility scope is cumulative according to the Javadoc documentation.
Standard Options, Advanced Options and Output
Standard Options
This tab contains the most commonly used Javadoc options.
Generate Hierarchy Tree
Select this option to generate a class hierarchy tree that includes all classes in all packages processed by the Javadoc utility.
Generate Navigation Bar
Select this field to generate a navigation bar.
Generate Index
Select this field to generate an index file that contain an alphabetic list of all classes, interfaces, constructors, methods, and fields.
Separate Index Per Letter
Select this field to generate separate index files per letter that contain an alphabetic list of all classes, interfaces, constructors, methods, and fields.
Use JDK 1.1 Format
Select this field to generate documentation files in Javadoc 1.1 format.
Advanced Options
This tab displays all other parameters that the Javadoc utility can accept. A short description for each option appears beside that option. For more detailed information please refer to the Javadoc home page at http://java.sun.com/j2se/javadoc/index.jsp.
Some advanced options to note are:
-group You MUST actually input this option with your groupheading and packagepattern.
e.g. -group "About Packages" "my.about.packages" -group "GUI Packages" "my.gui.packages"
-J You MUST actually input this option with the flag being passed.
e.g. -J-version
-link You MUST actually input this option with link(s) being passed.
e.g. -link extdocURL1 -link extdocURL2
-linkoffline You MUST actually input this option with link(s) and package-list location(s) being passed.
e.g. -linkoffline extdocURL1 packagelistLoc1 -linkoffline extdocURL2 packagelistLoc2
-tag You MUST actually input this option togeter with the tag name, location and tagheader.
e.g. -tag todo:cmf:"To Do:"
Output
This tab displays the output from the Javadoc utility.
If the display of output seems to hang, or documentation does not seem to be produced, it means there is an error in the documentation process. If this occurs, copy the string generated by this program to a command prompt/terminal, execute it and view the messages to fix any errors. This is a known bug in this program. It should be fixed by the next release.
If you believe that you have encountered a bug in BJavadocTool, or have a suggestion for an improvement that will be of use to many others, please send me e-mail at:
or
|
