Chapter 8. Jadexdoc Tool

Chapter 8. Jadexdoc Tool
Prev		Next

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.

8.1. Usage

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.

Figure 8.1. Generate Jadexdoc Dialog

The dialog offers several settings that can be adjusted before the generation is started via the Ok or Apply 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.

8.2. Source Files

The Jadexdoc tool will generate output originating from four different types of "source" files: Agent and Capability source files, package comment files, overview comment files, and miscellaneous unprocessed files.

Processing of source files. The Jadexdoc tool processes files that end with ".agent.xml" and ".capability.xml" plus other files described below. If you run the Jadexdoc tool by explicitly passing in individual source filenames, you can determine exactly which ADF files are processed. However, that is not how most developers want to work, as it is simpler to pass in package names.

Package Comment Files. Each package can have its own documentation comment, contained in its own "source" file, that the Jadexdoc tool will merge into the package summary page that it generates. You typically include in this comment any documentation that applies to the entire package.

To create a package comment file, you must name it package.html and place it in the package directory in the source tree along with the agent description files. The Jadexdoc tool will automatically look for this filename in this location. Notice that the filename is identical for all packages.

The content of the package comment file is one big documentation comment, written in HTML, like all other comments. 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 <body> and the first sentence.

When the Jadexdoc tool runs, it will automatically look for this file; if found, the Jadexdoc tool does the following:

Copies all content between <body> and </body> tags for processing.
Inserts the processed text at the bottom of the package summary page it generates, as shown in Package Summary.
Copies the first sentence of the package comment to the top of the package summary page. It also adds the package name and this first sentence to the list of packages on the overview page.

Overview Comment File. Each application or set of packages that you are documenting can have its own overview documentation comment, kept in its own "source" file, that the Jadexdoc tool will merge into the overview page that it generates. You typically include in this comment any documentation that applies to the entire application or set of packages.

To create an overview comment file, you can name the file anything you want, typically overview.html and place it anywhere, typically at the top level of the source tree. The content of the overview comment file is one big documentation comment, written in HTML, like the package comment file described previously. When you run the Jadexdoc tool, you specify the overview comment file name with the -overview option. The file is then processed similar to that of a package comment file.

Copies all content between <body> and </body> tags for processing.
Inserts the processed text at the bottom of the overview page it generates.
Copies the first sentence of the overview comment to the top of the overview summary page.

Miscellaneous Unprocessed Files. You can also include in your source any miscellaneous files that you want the Jadexdoc tool to copy to the destination directory. These typically includes graphic files, example agent description files, and self-standing HTML files whose content would overwhelm the documentation comment of a normal agent description file.

To include unprocessed files, put them in a directory called doc-files which can be a subdirectory of any package directory that contains source files. You can have one such subdirectory for each package. For example, if you want to include the image of a creature Creature.png in the jadex.examples.hunterprey.creature.CleverPrey agent documentation, you place that file in the jadex/examples/hunterprey/creature/doc-files/ directory. Notice the doc-files directory should not be located at jadex/examples/doc-files/ because examples does not directly contain any source files.

All links to these unprocessed files must be hard-coded, because the Jadexdoc tool does not look at the files, it simply copies the directory and all its contents to the destination. For example, the link in the CleverPrey.agent.xml doc comment might look like:

<!-- The image of the CleverPrey agent: <img src="doc-files/Creature.png"> -->

8.3. Generated Files

By default, Jadexdoc uses a standard doclet that generates HTML-formatted documentation. This doclet generates the following kinds of files (where each HTML "page" corresponds to a separate file). Note that Jadexdoc generates files with two types of names: those named after agents/capabilities, and those that are not (such as package-summary.html). Files in the latter group contain hyphens to prevent filename conflicts with those in the former group.

Basic Content Pages.

One agent (agentname.agent.html) or capability (capabilityname.capability.html) page for each agent or capability is documented.
One package page (package-summary.html) for each package it is documenting. The Jadexdoc tool will include any HTML text provided in a file named package.html in the package directory of the source tree.
One overview page (overview-summary.html) for the entire set of packages. This is the front page of the generated document. The Jadexdoc tool will include any HTML text provided in a file specified with the -overview option. Note that this file is created only if you pass into Jadexdoc two or more package names.

Cross-Reference Pages.

One agent/capability hierarchy page for the entire set of packages (overview-tree.html). To view this, click on Overview in the navigation bar, then click on Tree.
One agent/capability hierarchy page for each package (package-tree.html). To view this, go to a particular package, agent or capability page; click Tree to display the hierarchy for that package.
An index (index-*.html) of all agent, capabilities, beliefs, plans, goals, events and expressions names, alphabetically arranged.

Support Files.

A help page (help-doc.html) that describes the navigation bar and the above pages. You can provide your own custom help file to override the default using -helpfile.
One index.html file which creates the HTML frames for display. This is the file you load to display the front page with frames. This file itself contains no text content. Several frame files (*-frame.html) containing lists of packages, agents and capabilities, used when HTML frames are being displayed.
A style sheet file (stylesheet.css) that controls a limited amount of color, font family, font size, font style and positioning on the generated pages.
A doc-files directory that holds any image, example, source code or other files that you want copied to the destination directory.

8.4. Documentation Comments

Commenting the Source Code. You can include documentation comments in the agent description files, ahead of declarations for any agent, capability, plan, goal, event or expression, etc. You can also create comments for each package and another one for the overview, though their syntax is slightly different. The comments in the agent description files are regular xml-comments consisting of the characters between the characters  that end it. The text in a comment can continue onto multiple lines.

<!--
    This is the typical format of a simple documentation
    comment that spans multiple lines.
-->

<!-- To save space you can also put a comment on one line. -->

Placement of comments. Documentation comments are recognized only when placed immediately before agent, capability, belief, goal, plan, event or expression declarations. Only one documentation comment per declaration statement is recognized by the Jadexdoc tool.

<!-- This is the comment for the agent 'MyAgent' -->
<agent name="MyAgent" package="jadex.examples.myagents">
    <beliefs>
        <!-- The comment for the belief 'MyBelief' -->
        <belief name="MyBelief" class="Object"/>
    </beliefs>
</agent>

Comments are written in HTML. The texts can be written in HTML, in that they should use HTML entities and can use HTML tags. You can use whichever version of HTML your browser supports. The bold HTML tag  is shown in the following example.

<!-- This is a <b>documentation</b> comment. -->

First sentence. The first sentence of each documentation comment should be a summary sentence, containing a concise but complete description of the declared member. This sentence ends at the first period that is followed by a blank, tab, or line terminator. The Jadexdoc tool copies this first sentence to the member summary at the top of the HTML page. For convenience, Jadexdoc strips any html tags from this sentence, when it is displayed in a summary table.

8.5. Options

The Jadexdoc tool uses a standard doclet to determine its output. The Jadexdoc tool provides a set of command-line options that can be used with any doclet. These options are described below under the sub-heading Section 8.5.1, “Jadexdoc Options”. The standard doclet provides an additional set of command-line options that are described below under the sub-heading Options Provided by the Standard Doclet. All option names are case-insensitive, though their arguments can be case-sensitive.

8.5.1. Jadexdoc Options

-subpackages pck1:pck2:...

Generates documentation from source files in the specified packages and recursively in their subpackages. This option is useful when adding new subpackages to the source code, as they are automatically included. Each package argument is any top-level subpackage (such as jadex) or fully qualified package (such as jadex.examples) that does not need to contain source files. Arguments are separated by colons (on all operating systems). Wildcards are not needed or allowed.

java jadex.tools.jadexdoc.Main -d docs -subpackages jadex.examples.hunterprey:jadex.examples.cleanerworld

You can use -subpackages in conjunction with -exclude to exclude specific packages.

-exclude pck1:pck2:...

Unconditionally excludes the specified packages and their subpackages from the list formed by -subpackages. It excludes those packages even if they would otherwise be included by some previous or later -subpackages option.

java jadex.tools.jadexdoc.Main -d docs -subpackages jadex -exclude jadex.planlib:jadex.examples.testcases

-help

Displays the online help, which lists these Jadexdoc and doclet command line options.

-quiet

Shuts off non-error and non-warning messages, leaving only the warnings and errors appear, making them easier to view. Also suppresses the version string.

8.5.2. Options Provided by the Standard Doclet

-d directory

Specifies the destination directory where Jadexdoc saves the generated HTML files. Omitting this option causes the files to be saved to the current directory. The value directory can be absolute, or relative to the current working directory. The destination directory is automatically created when Jadexdoc is run. For example, the following generates the documentation for the package jadex.examples.testcases and saves the results in the user/doc directory: java jadex.tools.jadexdoc.Main -d user/doc jadex.examples.testcases

-overview path/filename

Specifies that Jadexdoc should retrieve the text for the overview documentation from the "source" file specified by path/filename and place it on the Overview page (overview-summary.html). While you can use any name you want for filename and place it anywhere you want for path, a typical thing to do is to name it overview.html and place it in the source tree at the directory that contains the topmost package directories. Note that the overview page is created only if you pass into Jadexdoc two or more package names. The title on the overview page is set by -doctitle.

-splitindex

Splits the index file into multiple files, alphabetically, one file per letter, plus a file for any index entries that start with non-alphabetical characters.

-windowtitle title

Specifies the title to be placed in the HTML <title> tag. This appears in the window title and in any browser bookmarks (favorite places) that someone creates for this page. This title should not contain any HTML tags, as the browser will not properly interpret them. Any internal quotation marks within title may have to be escaped. If -windowtitle is omitted, the Jadexdoc tool uses the value of -doctitle for this option.

java jadex.tools.jadexdoc.Main -windowtitle "Jadex Examples" jadex.examples

-doctitle 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 may contain html tags and white space, though if it does, it must be enclosed in quotes. Any internal quotation marks within title may have to be escaped.

java jadex.tools.jadexdoc.Main -doctitle "Jadex Agent Dokumentation" jadex.examples.testcases

-header header

Specifies the header text to be placed at the top of each output file. The header will be placed to the right of the upper navigation bar. header may contain HTML tags and white space, though if it does, it must be enclosed in quotes. Any internal quotation marks within header may have to be escaped.

java jadex.tools.jadexdoc.Main -header "Jadex Platform 0.93" jadex.examples.testcases

-footer footer

Specifies the footer text to be placed at the bottom of each output file. The footer will be placed to the right of the lower navigation bar. footer may contain html tags and white space, though if it does, it must be enclosed in quotes. Any internal quotation marks within footer may have to be escaped.

-bottom text

Specifies the text to be placed at the bottom of each output file. The text will be placed at the bottom of the page, below the lower navigation bar. The text may contain HTML tags and white space, though if it does, it must be enclosed in quotes. Any internal quotation marks within text may have to be escaped.

-link extdocURL

The -link option enables you to link to java classes referenced to by your members in the agent description file. For these links to go to valid pages, you must know where those HTML pages are located, and specify that location with extdocURL. This allows, for instance, a jadex doc file to link to java.* documentation on http://java.sun.com. When Jadexdoc is run without the -link option, when it encounters a java class, it prints the fully qualified name with no link. However, when the -link option is used, the Jadexdoc tool searches the package-list file at the specified extdocURL location for that package name. If it finds the package name, it creates a link to the external javadoc location.

extdocURL is the absolute or relative URL of the directory containing the external javadoc-generated documentation you want to link to. Examples are shown below. The package-list file must be found in this directory (otherwise, use -linkoffline). The Jadexdoc tool reads the package names from the package-list file and then links to those packages at that URL. When the Jadexdoc tool is run, the extdocURL value is copied literally into the <A HREF> links that are created. Therefore, extdocURL must be the URL to the directory, not to a file. You can use an absolute link for extdocURL to enable your docs to link to a document on any website, or can use a relative link to link only to a relative location. If relative, the value you pass in should be the relative path from the destination directory (specified with -d) to the directory containing the packages being linked to. In all cases, and on all operating systems, you should use a forward slash as the separator, whether the URL is absolute or relative, and "http:" or "file:" based (as specified in theURL Memo).

Absolute http: based link:

-link http://<host>/<directory>/<directory>/.../<name>

Absolute file: based link:

-link file://<host>/<directory>/<directory>/.../<name>

Relative link:

-link <directory>/<directory>/.../<name>

You can specify multiple -link options in a given Jadexdoc run to link to multiple documents.

Choosing between -linkoffline and -link. Use -link: when using a relative path to the external API document, or when using an absolute URL to the external API document, if your shell allows a program to open a connection to that URL for reading.

Use -linkoffline: when using an absolute URL to the external API document, if your shell does not allow a program to open a connection to that URL for reading. This can occur if you are behind a firewall and the document you want to link to is on the other side.

Example 8.1. Example using absolute links to the external docs

Let's say you want to link to the Java 2 Platform packages at http://java.sun.com/j2se/1.5.0/docs/api/. The following command generates documentation for the package jadex.examples with links to the Java 2 Platform packages.

java jadex.tools.jadexdoc.Main -link http://java.sun.com/j2se/1.5.0/docs/api/ -subpackages jadex.examples

Example 8.2. Example using relative links to the external docs

Let's say you have user defined java packages whose docs are generated with the Javadoc tool. Then you use the Jadexdoc tool to document the corresponding agent description files and those docs are separated by a relative path. In this example, the API (Application Programming Interface) packages reside in docs/api/jadex/examples and the ADF (agent description files) packages in docs/adf/jadex/examples. Assuming the API package documentation is already generated, and that docs is the current directory, you would document the ADF package with links to the API documentation by running:

java jadex.tools.jadexdoc.Main -d ../adf -link ../api -subpackages jadex.examples

The -link argument is relative to the destination directory. In order to avoid broken links, all of the documentation for the external references must exist at the specified URLs. The Jadexdoc tool will not check that these pages exist only that the package-list exists.

Multiple Links. You can supply multiple -link options to link to any number of external generated documents. Specify a different link option for each external document to link to:

java jadex.tools.jadexdoc.Main -link extdocURL1 -link extdocURL2 ... -subpackages jadex.examples

where extdocURL1, extdocURL2, ... point respectively to the roots of external documents, each of which contains a file named package-list.

-linkoffline extdocURL packagelistLoc

This option is a variation of -link; they both create links to javadoc-generated documentation for external referenced classes. Use the -linkoffline option when linking to a document on the web when the Javadoc tool itself is "offline" that is, it cannot access the document through a web connection.

The -linkoffline option takes two arguments the first for the string to be embedded in the <a href> links, the second telling it where to find package-list:

extdocURL is the absolute or relative URL of the directory containing the external javadoc-generated documentation you want to link to. If relative, the value should be the relative path from the destination directory (specified with -d) to the root of the packages being linked to. For more details, see extdocURL in the -link option.
packagelistLoc is the path or URL to the directory containing the package-list file for the external documentation. This can be a URL (http: or file:) or file path, and can be absolute or relative. If relative, make it relative to the current directory from where javadoc was run. Do not include the package-list filename.

You can specify multiple -linkoffline options in a given Jadexdoc run.

-group groupheading packagepattern:packagepattern:...

Separates packages on the overview page into whatever groups you specify, one group per table. You specify each group with a different -group option. The groups appear on the page in the order specified on the command line; packages are alphabetized within a group. For a given -group option, the packages matching the list of packagepattern expressions appear in a table with the heading groupheading.

groupheading can be any text, and can include white space. This text is placed in the table heading for the group.

packagepattern can be any package name, or can be the start of any package name followed by an asterisk (*). The asterisk is a wildcard meaning "match any characters". This is the only wildcard allowed. Multiple patterns can be included in a group by separating them with colons (:).

If using an asterisk in a pattern or pattern list, the pattern list must be inside quotes, such as "jadex.examples*"

If you do not supply any -group option, all packages are placed in one group with the heading Packages. If the groups do not include all documented packages, any leftover packages appear in a separate group with the heading Other Packages.

java jadex.tools.jadexdoc.Main -group "Core Packages" "jadex.planlib" -group "Hunterprey Packages" "jadex.examples.hunterprey*" -subpackages jadex.examples

-notree

Omits the agent/capability hierarchy pages from the generated docs. These are the pages you reach using the "Tree" button in the navigation bar. The hierarchy is produced by default.

-noindex

Omits the index from the generated docs. The index is produced by default.

-nohelp

Omits the "Help" link in the navigation bars at the top and bottom of each page of output.

-nonavbar

Prevents the generation of the navigation bar, header and footer, otherwise found at the top and bottom of the generated pages. Has no affect on the "bottom" option. The -nonavbar option is useful when you are interested only in the content and have no need for navigation.

-helpfile path/filename

Specifies the path of an alternate help file path/filename that the "Help" link in the top and bottom navigation bars link to. Without this option, the Jadexdoc tool automatically creates a help file help-doc.html. This option enables you to override this default. The filename can be any name. The Jadexdoc tool will adjust the links in the navigation bar accordingly.

java jadex.tools.jadexdoc.Main -helpfile C:\user\myhelp.html -subpackages jadex.examples

-stylesheetfile path/filename

Specifies the path of an alternate HTML stylesheet file. Without this option, the Jadexdoc tool automatically creates a stylesheet file stylesheet.css. This option enables you to override this default. The filename can be any name.

java jadex.tools.jadexdoc.Main -stylesheetfile C:\user\mystylesheet.css -subpackages jadex.examples

-docfilessubdirs

Enables deep copying of "doc-files" directories. In other words, subdirectories and all contents are recursively copied to the destination. For example, the directory doc-files/example/images and all its contents would now be copied. There is also an option to exclude subdirectories.

-excludedocfilessubdir name1:name2...

Excludes any doc-files subdirectories with the given names.

-noqualifier all | packagename1:packagename2:...

Omits qualifying package name from ahead of agent/capability and class/interface names in output. The argument to -noqualifier is either all (all package qualifiers are omitted) or a colon-separated list of packages, with wildcards, to be removed as qualifiers. The package name is removed from places where agent/capability or class/interface names appear.

-nocomment

Suppress the entire comment body, including the main description, generating only declarations.

Prev		Next
Chapter 7. Beanynizer	Home	Appendix A. Jadex Remote Monitoring Agent