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"> -->