The Jedi Tutorial
Documenting your sources
Now that the code for our application is complete, it is time wo write
some documentation. Java provides a standard way to write documentation
and a tool to transform it into nicely formated html.
Jedi also supports this feature.
In our HelloWorld class, click
on the tab 'Class: JavaDoc' to switch
the editor to the javadoc mode. The toolbar contains a few icons for the
standard javadoc tags. Click on the 'author'
icon and enter your name in the text editor. Then click the 'version'
icon and enter a version number, e.g. '0.77.2beta5pl44'. You may
also type in some text describing the class. Similarly, documentation
for each method can be created using the 'Method:
JavaDoc' tab. Standard tags for methods appear in the toolbar and
you can write some method documentation now. When you are done, click the
'compile' icon.
The
'javadoc' window will show up. It contains
a lot of settings, most of which we will ignore now. What needs to be set
is the path of the 'javadoc' tool in
the topmost line. Set it to '<javadir>/bin/javadoc'. Then check
the 'include author' and 'include
version' boxes below. Now set the target directory, where you want
the docs to be created. The string field is located at the top of the lower
half. You can enter a path manually or use the filerequester button. Choose
a path of your preference, but make sure you have write access. Now hit
the 'Generate JavaDoc' button. Jedi
will display what it is doing and what files are created. You can then
browse them using Netscape or any html-browser.
Accessing your own documentation
The previous section of this tutorial has introduced Jedi's context
help feature. It can not only be used to gain quick access to JDK
documentation, you can also configure it to access your newly created documentation.
To do this, open the 'JavaDoc API Directories'
panel from the 'Prefs' menu again.
Add the path you just stated as target directory when creating your documentation.
Then hit 'Ok'. Jedi will generate
a new index (which will again take some time).
Now we are ready to test it. Select the 'main' method in the
browser, activate the editor and type 'main', move the cursor
1 character to the left (so that is over the 'main') and push
(not release) the right button over the help icon. You should see the following
choice:
main(java.lang.String[]) of class helloworld.HelloWorld
Select it and a browser should pop up, showing the documentation for
your class (scroll to the top to see the class docs you just wrote). If
that works, delete the word 'main' and remove the new path from
the 'JavaDoc API directories'. These
were just for testing. You can of course add custom paths again later,
when you have written some real documentation. Note, however, that Jedi
needs to rebuild its index whenever documentation changes.