-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 "<b>Jadex Agent Dokumentation<b>" 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 "<b>Jadex Platform</b><br>0.96" 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 9.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/javase/6/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/javase/6/docs/api/ -subpackages jadex.examples
Example 9.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.