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