The Jadexdoc Tool is a documentation tool similar to the Javadoc tool.
It provides the ability to generate HTML pages for
ADF (Agent Description File) documentation from Jadex source files.
The Jadexdoc tool parses the declarations and documentation comments
in a set of agent description files and produces a corresponding set of
HTML pages describing the agents, capabilities, beliefs,
goals, plans, events and expressions. You can use it to generate the ADF
documentation or the implementation documentation for a set of agents and
capabilities. You can run the Jadexdoc tool on entire packages, individual
source files, or both. When documenting entire packages, you can either traverse
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 (.agent.xml
or .capability.xml
)
filenames.
You can start the Jadexdoc tool from a console via:
java jadex.tools.jadexdoc.Main [options] [packagenames] [sourcefilenames] [-subpackage pck1:..]Description. Arguments can be in any order. See processing of Source Files for details on how the Jadexdoc tool determines which source files to process.
options. Command-line options, as specified in this document. The section options below contains examples of Jadexdoc options.
packagenames.
A series of names of packages, separated by spaces, such as
jadex.examples jadex.planlib
.
You must separately specify each package you want to document.
Wildcards are not allowed; use -subpackages
for recursion.
For further details see the section Section 8.5, “Options”.
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 Jadexdoc tool will process every file whose name ends with ".agent.xml" or ".capability.xml".
-subpackages pck1:pck2:...
Generates documentation from source files in the specified packages and
recursively in their subpackages. An alternative to supplying packagenames or
sourcefilenames.
Generation Dialog. It is also possible to start Jadexdoc via user interface. The command to start the user interface generation dialog (see Figure 8.1, “Generate Jadexdoc Dialog”) is:
java jadex.tools.jadexdoc.GenerateDialog
Another possibility to start the dialog is diectly from the Jadex Control Center. You can select an agent (or capability) or a package in the model explorer of the starter perspective. Clicking in the toolbar the "Generate Jadexdoc" will open the dialog in which the generation settings can be specified. After successful generation a browser will be opened and the generated documentation is shown.
The dialog offers several settings that can be adjusted before the generation is started via the
or buttons. The documentation may take a while so the progress of the generation process is shown in the progress bar above the buttons.Whole project. Documentation for the whole project and all contained packages will be created. This option is only available when the dialog is started from the Control Center.
Selected Package. Documentation for the selected package or file is generated. If the tool is started from the Control Center the currently selected package will be shown. If the dialog is started via command-line you can use the
button to select a file or directory to document.Include subdirectories. If turned on all subpackages of the selected package are automatically included in the generation process.
Output directory. The standard output directory is the current directory. The
button can be used to select another appropriate target directory.Overview page. The overview page represents the top-level page for the whole generated documentation and contains information about the contained packages. The
button can be used to select a custom overview HTML page. The overview page will only be included when the corresponding check box is selected.Document title. Specifies the title to be placed near the top of the overview summary file. The title will be placed as a centered, level-one heading directly beneath the upper navigation bar. The title will only be included when the corresponding check box is selected.
Basic options. The basic options can be used to turn on/off several generation features. The hierarchy tree is a page containing agents and capabilities displayed in usage relationships. The navigation bar offers possibilities to refer to related documentation pages. It can be turned off if you are interested only in the content and have no need for navigation, e.g. when converting the files to PostScript or PDF for print only. The index holds an alphabetical list of elements. It can be adjusted with an options in a way that only one letter per page is generated.
Extra options. In the extra options text field an arbitrary number of additional Jadexdoc command line options can be specified.
Generate Javadoc and link to Jadexdoc. If selected in a first run Javadoc will be invoked to produce the Javadoc documentation for the selected packages. In a second run Jadexdoc will additionally create the agent-related documentation and link it with the formerly produced class information.
Link to J2SE online documentation. If selected the generated documentation will be connected to the online Javadoc of the Java Development Kit 1.5.
Link to J2SE online documentation. If selected the generated documentation will be connected to the online Javadoc of the Java Development Kit 1.5.
Open generated documentation in browser.
If selected the generated documentation (index.html
)
will be opened in the default browser of the system.