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. The Jadexdoc tools can be run together with the Javadoc
tool in order to document the agents as well as the used Java classes.
Jadexdoc will use the generated Javadoc documentation and generate links for
the corresponding classes.
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.
The easiest way to use the Jadexdoc tool is via the plugin which provides a gui simplifying the documentation task:
There are three basic panels in this graphical tool. The model tree on the left hand side, the package panel and the settings panel. They will be described in detail below.
On the left upper side there is the model tree which is already known from other tools such as the starter tool (see Section 3.1, “Model Tree”):
With this panel you can manage adding packages or single files to your selection of files of which you want to create the Javadoc/Jadexdoc. For this purpose the following actions are available via popup (and also partially via the tool bar above):
For adding the selected package to the list of packages to document.
For adding the selected package and all recursivly contained subpackages
to the list of packages to document.
For removing the selected package to the list of packages to document.
For removing the selected package and all recursivly contained subpackages
to the list of packages to document.
In the middle you can find a panel which displays selections of “Packages”, “Source Paths”, “Class Paths” and “URL Links”:
The“Packages” tab shows the packages and files that should be documented by the Jadexdoc and Javadoc tools.
In the “Source Paths” tab the path(s) to the sources of the packages and files to document can be defined. In case of Jadexdoc source paths are normally not that important because the ADF files are contained in the "classes" folder, too. With respect to Javadoc source path are more important as Javadoc always needs the Java source files for accessing the Javadoc comments which are not present in the compiled classes any more.
In the “Class Paths” tab the class path can be edited. This can be done either by hand or by clicking on the “Fetch” button which results in fetching the currently used class paths.
If you finally choose the tab “URL Links” you can specify locations you want to cross-link to in your doc-files. If you click on fetch this will insert an entry for the URL to the Standard JDK Java API. This will enable Javadoc and Jadexdoc to generate links for the standard Java classes such as String, Integer etc.
On the right hand side you can find the settings panel, where some detailed settings for Javadoc and Jadexdoc and be defined:
The "Include subpackes" check box can be used for automatically including subpackages. This means if this option is checked the tools will generate documentation for all selected packages (and files) and all of the recursively contained subpackages.
Via the "Output directory" textfield it can be defined to which directory the documentation should be generated. The standard output directory is the current directory. The
button can be used to select another appropriate target directory.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.The "Document title" option can be used for specifying 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.
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.
The "Generate Javadoc" check box can be used to turn on/off the invocation of the Javadoc tool.
In the extra options text field an arbitrary number of additional Javadoc command line options can be specified.
The "Javadoc program location" option allows for specifying the program location of the Javadoc tool, which belongs to the standard JDK edition.
The "Generate Jadexdoc" check box can be used to turn on/off the invocation of the Jadexdoc tool.
In the extra options text field an arbitrary number of additional Jadexdoc command line options can be specified.
The "Java program location" option allows for specifying the program location of the Java program (e.g. java.exe on Windows systems), which belongs to the standard JDK edition and is required for the invocation of the Jadexdoc tool.
During the documentation generation, there will appear an animated icon in the bottom
right corner. While running Javadoc, it shows a Java icon scanned by a red bar
, while running Jadexdoc, an icon with an agent scanned by a red bar is displayed
.
The Jadexdoc and Javadoc tools both use the standard Java output and error streams (System.out and System.err) for printing out information about the generation progress. The console panel of the JCC allows for inspecting these outputs directly in the tool (see also Section 2.1, “Using the JCC”).
On the top right of the console outputs, there are two buttons. With the left one, you can turn on and off the console output during a run, with the right one you can clear the console.