|
What
is JavadocViewer 1.1?
How
to use JavadocViewer 1.1
Software
Requirements
Further
Documentation
What's
new in Version 1.1
Known
Bugs and Limitations
Legal
Stuff
|
What is
JavadocViewer 1.1?
Javadoc is a tool that comes with the Java Development
Kit and it automatically creates an API documentation from comments
embedded into the source code. Javadoc can be extended by Doclets to
output the documentation in any format. The default Doclet produces
HTML files that can be viewed with any standard web browser. All the
documentation for the Java API is built this way.
This approach has advantages but suffers from the static
HTML interface. The obvious solution is to implement a custom Doclet
and a matching viewer in Java - creating a rich, interactive interface
without sacrificing platform independence and without abandoning the
existing architecture. And that's where JavadocViewer comes in.
I came up with the idea to design such a tool when
writing a term paper at university. I recently found some time to do a
complete re-programming and this is the result of these efforts. The
JavadocViewer consists of a Doclet and a Viewer component. The Doclet
uses the Standard Doclet provided by Sun to write the HTML
documentation and creates a file with meta-data for the Viewer. The
Doclet might also archive both the meta-data and all HTML docs into a
single file using the JAR library. The Viewer is a Swing GUI that loads
the meta-data and HTML files and displays both in a tree view, an index
and a browser window. Version 1.1 adds a powerful search engine
(Jakarta Lucene by the Apache Software Foundation) and improves
navigation.
How to use
JavadocViewer 1.1
As said, there are two components to JavadocViewer: The
Doclet and the Viewer.
The easier part is to run the Viewer. All necessary
class files and images are provided in the archive viewer.jar. You start up the
Viewer simply by running:
java -jar viewer.jar
The JAR file is executable so there is no need to
specify a main class. Run with no command line arguments, the Viewer
starts with an empty window. You can then select Open from the File menu in order to load a
documentation. You might also give the filename or URL of the
documentation as command line option. The JavdocViewer comes with its
own documentation as demo material. To start the Viewer and open the
demo documentation type:
java -jar viewer.jar
documentation.jar
The Doclet is a bit harder to run. Basically, you run
the javadoc tool with
all the standard options but using the JavadocViewerDoclet.
The fist pitfall here is that the JavadocViewer Doclet will need access
to the Standard Doclet in order to write the HTML files. Hence, you
will need to add the file tools.jar
found in the lib
directory of the Java SDK to your classpath. You might also have to use
option docletpath if
you do not yet have doclet.jar
in your classpath. Ok, here comes an example:
javadoc -classpath
.;c:\java\lib\tools.jar -docletpath doclet.jar -doclet
javadocViewer.javadocViewerDoclet mypackage
That's not rocket science, is it? Add any standard
options you like. However, here are some remarks about special options:
| -d |
The
JavadocViewer Doclet will save its results in this directory. If this
option has not been specified, the current directory will be used.
Hence, the meta-data should alwas end up in the root directory of the
HTML files. |
| -doctitle |
The JavadocViewer will
display this at the root of the tree view so it might be a good idea to
specify something here. Otherwise, a default text will be used. |
-noindex
-nohelp |
These options toggle writing
of special documents. The JavadocViewer does not use these documents so
you might safely turn them off. |
| -nonavbar |
The navigation bar is
displayed on top of every page. In JavadocViewer, the bar works only
partially and rendering is a bit ugly thanks to the poor HTML
implementation in Swing. You might consider turning creation off. |
|
|
The JavadocViewerDoclet adds three custom options:
| -ser <filename> |
Filename of the meta-data file. The meta-data file
is a serialized Java object, therefore, the filename extension should
be .ser . It this
option is omitted, a default filename (doc.ser)
is used.
|
| -jar <filename> |
Filename of the JAR file. If
this option is omitted, no JAR file is created. If you choose to use a
JAR file, the -ser
option will be ignored and the default name for the meta-data file will
be used. This will ensure that the Viewer knows which entry in the JAR
archive represents the meta-data. |
| -nosearch |
The Jakarta Lucene search
engine creates a search index and saves it into a bunch of files in a
subdirectory of the target directory. The -nosearch
option toggles creation of the search index off. Obviously, you won't
be able to run a full text query in the Viewer without the search index
later. Searching has not yet been implemented for documentation located
on a remote server so if you intend to deploy the JavadocViewer
documentation this way you might safely turn the search index off. |
Here comes a full-scale example:
javadoc -classpath
.;C:\java\lib\tools.jar -docletpath doclet.jar -d ..\documentation -jar
documentation.jar -noindex -nohelp -doclet
javadocViewer.JavadocViewerDoclet -doctitle "My API" myfirstpackage
mysecondpackage
Software
Requirements
Requirements for the Viewer and the Doclet differ.
The Doclet obviously requires the Javadoc tool and the
standard Doclet. Both come with the Sun JDK. The Doclet API was
introduced with Javadoc 1.2 and the JavadocViewer has been developed
with that version. Though not tested, any later version should do as
well. I'm not exactly sure but I suppose that Javadoc 1.2 came with
Java 2 SE so any Java 2 SE SDK should be supported.
The Viewer does not use the Javadoc tool at all.
Therefore, it will run in any JRE that supports Swing. Any Java 2 SE
Runtime Environment should do. If you are using a JAR file with search
index files you will need ample disk space in your temporary directory.
Further
Documentation
As said, that JavadocViewer comes with its own
documentation as demo material. See How
to Use JavadocViewer on how to view these docs. You might
also extract the HTML files from the archive and view them using your
web browser. To extract them type:
jar xf documentation.jar
If you have any further questions please contact the author or visit his
homepage at www.michaelhilberg.de.
What's New in
Version 1.1
- Added search:
- The Doclet uses the Jakarta Lucene library to
create a search index
- The Viewer has been extended by a search panel
- -nosearch
option has been added to the Doclet
- Other new features:
- Index scrolls when a key has been pressed
- Public elements now rendered in bold font
- Added HTML files documenting class hierarchy,
usage, deprecation and serialization to tree view and JAR file
- Added About dialog to Viewer
- Minor bugfixes and optimizations:
- Sorting in index is now case-insensitive
- Revised selection behaviour
- Display overview page when new documentation is
loaded
- Removed horizontal scrollbars on index and tree
view
- Made Doclet output consistent with output of
standard Doclet
- Fixed start page if only one package is documented
- Fixed bug in history
- Doclet now prints a warning if you specify a
custom filename for the meta-data file while creating a JAR file
Known Bugs and
Limitations
- You may specify any combination of package names and
source filenames on Javadoc's command line. JavadocViewer, however,
only recognizes package names. It will ignore source filenames and an
exception will be thrown if no package names have been specified. This
is a bug and will be fixed in the next relaese. Domenico, thanks for
reporting it.
- The Viewer can't be used for Applets. The Swing HTML
browser (JEditorPane)
throws a SecurityException
when trying to load an HTML file from the web server despite the fact
that the Applet should be allowed to download from its own server.
Furthermore, the Applet failed to load its icons from the JAR file.
This, however, should be a minor issue. Any help with the JEditorPane would be greatly
appreciated.
- You might have noticed that the rendering of the HTML
files is not exactly beautiful. I'm aware of that and I am thinking of
alternatives to JEditorPane.
I'm also hoping that Sun might increase the functionality of the HTML
renderer in later JDK releases.
- The JEditorPane
is not thread-safe. If it is in progress of loading a HTML file and if
you instruct it to load a different HTML file, you end up with obscure
exceptions. This happens frequently if you click on entries in the tree
view without waiting for the current page to load. Anyway, nothing
really happens when the exception is thrown.
- When archiving the files you can not use a meta-data
filename other then the standard one. I tried to add the filename to
the JAR file's Manifest but apparently failed to do so. This is to be
solved in later releases. The Doclet now prints a warning.
- The data model of JavadocViewer 1.1 differs from that
of version 1.0. The 1.1 Viewer won't load meta-data files of version
1.0.
- Searching is not supported for documentation loaded
from a remote server. This is due to the fact that the search engined
used needs access to the search index files through the local file
system. To be added in later versions.
Legal Stuff
JavadocViewer 1.1
Copyright (c) 2002 Michael Hilberg
Permission is hereby granted, free of charge, to any
person obtaining a copy of this software and associated documentation
files (the "Software"), to deal in the Software without restriction,
including without limitation the rights to use, copy, modify, merge,
publish, distribute, sublicense, and/or sell copies of the Software,
and to permit persons to whom the Software is furnished to do so,
subject to the following conditions:
The above copyright notice and this permission notice
shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF
ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Java is a registered trademark of Sun Mircosystems Inc.
Jakarta Lucene
/* ====================================================================
* The Apache Software License, Version 1.1
*
* Copyright (c) 2001 The Apache Software Foundation. All rights
* reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
*
* 1. Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
*
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in
* the documentation and/or other materials provided with the
* distribution.
*
* 3. The end-user documentation included with the redistribution,
* if any, must include the following acknowledgment:
* "This product includes software developed by the
* Apache Software Foundation (http://www.apache.org/)."
* Alternately, this acknowledgment may appear in the software itself,
* if and wherever such third-party acknowledgments normally appear.
*
* 4. The names "Apache" and "Apache Software Foundation" and
* "Apache Lucene" must not be used to endorse or promote products
* derived from this software without prior written permission. For
* written permission, please contact apache@apache.org.
*
* 5. Products derived from this software may not be called "Apache",
* "Apache Lucene", nor may "Apache" appear in their name, without
* prior written permission of the Apache Software Foundation.
*
* THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
* WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
* OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
* DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
* ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
* USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
* ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
* OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
* OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
* SUCH DAMAGE.
* ====================================================================
*
* This software consists of voluntary contributions made by many
* individuals on behalf of the Apache Software Foundation. For more
* information on the Apache Software Foundation, please see
* <http://www.apache.org/>.
*/
|