Javadoc Plugin

Copyright (c) 2003 by Robert Swarr.
Current maintainer: Robert Swarr (robert.swarr@agoralogos.net)

Foreword

During more than twenty years of programming experience, I've observed that software documentation falls out of date with the software shortly after the first release. Why? There are several reasons. First, software is a codification of some part of human knowledge. And like human knowledge it is always in flux, changing and even expanding. Secondly, most software usually is created and maintained in great haste. Developers never have enough time for changing the code and maintaining the documentation (we'll take care of it after the release is done). Consequently, you can't trust documentation. If you want to know what the code really does, you have to read it. Unfortunately, reading code is a time-consuming way to learn software, which provides the motivation for creating documentation.

So what is the solution? Answer: Javadoc -- Sun got this one right. Putting the documentation in the source code so that both can be updated simultaneously makes it much easier to keep documentation current. It's true that software documentation requires both personal and organizational discipline, but the Javadoc utility facilitates this process. Also, developers don't have to spend time on formatting -- the Javadoc utility performs the formatting when it generates the documentation from the Javadoc comments.

The reason I developed this plugin was so that I could generate the Javadoc within jEdit as I was writing the comments. I'd also suggest trying the JavaStyle plugin. It's a really useful plugin that generates much of the text for the Javadoc comments.

Contents

1. Introduction
2. Requirements
3. Installation
4. Usage
5. Options
6. Problems/Issues

1. Introduction

The Javadoc Plugin allows you to execute the Javadoc utility with a point and click interface within jEdit, as you create and edit Javadoc comments. While you're editing the source code and Javadoc comments you can generate and review the Javadoc with a few mouseclicks

You can set Javadoc command line parameters with the Javadoc Options menu selection and then run Javadoc with the Execute Javadoc menu selection.

The Javadoc Plugin is configured with some defaults, but you will need to set several options such as sourcepath, classpath and output directory.

2. Requirements

• jEdit >= 4.0pre1
• plugin InfoViewer >= 1.2
• plugin ErrorList >= 1.2
• plugin Console >= 3.1
• a Java Development Kit (JDK), but not a Java Runtime Environment (JRE) !

3. Installation

I'd recommend using the jEdit Plugin Manager to install the Javadoc Plugin or any other plugin. The Plugin Manager will download all of the required plugins. If you download plugins manually, you have to look up the dependencies on the website and download all of the required plugins yourself. Anyway, if you miss something, don't worry. jEdit will handle it gracefully and output an error message telling you what is missing.

4. Usage

• Execute Javadoc

  Executes Javadoc using the options currently configured.

• Javadoc Help

  Executes Javadoc -help and displays the output on the console.

• View Javadoc

  Displays Javadoc contained in the destination directory using the InfoViewer Plugin (see Javadoc Options for setting of the destination directory).

• Javadoc Options

  Displays options dialog to set Javadoc options.The options dialog has six tabs for different groups of options:

  • General: packagenames, sourcefiles, and @files command line parameters
  • Visibility: setting access attribute options/li>
  • Paths: set path options
  • Directories: set directory options
  • Flags: set boolean options
  • Formatting: set titles, header and footer options

To speed the JavaDoc development process I'd suggest using the JavaStyle plugin to help create the Javadoc comments and then use the View Javadoc action to view the HTML within jEdit. One caution -- after you view the HTML file, you'll need to select another HTML file with InfoViewer in order to save edit buffer changes because of a locking conflict between jEdit and the InfoViewer plugin. these two plugins together with the Javadoc plugin will allow you to create documentation quickly and efficiently.

5. Options

The Javadoc Plugin supports most Javadoc command line options. These options can be set using the Javadoc Options menu selection.

• -author
• -bootclasspath classpathlist
• -bottom text
• -classpath classpathlist
• -d directory
• -doctitle title
• -extdirs dirlist
• -footer footer
• -header header
• -help (Javadoc Help Menu Selection)
• -nodeprecated
• -nodeprecatedlist
• -nohelp
• -noindex
• -nonavbar
• -nosince
• -notree
• -package
• -private
• -protected
• -public
• -serialwarn
• -sourcepath sourcepathlist
• -splitindex
• -use
• -verbose
• -version
• -windowtitle title

6. Problems/Issues

Java 1.4.1 -- Display of Javascript on web page.

In Java version 1.4.1 the JavaDoc program began generating script tags containing Javascript. The InfoViewer plugin uses the setPage() method of the javax.swing.JEditorPane class to display HTML pages. This Swing method doesn't support script tags. According to the HTML specification, the proper action for browsers that don't support the script tag is to display whatever is between the tags as HTML. But, this action is confusing -- what you see displayed looks like a browser error. For example:

       function asd()
       {
       parent.document.title="Overview (JDocPlugin)";
       }
   

I'm working on adding a JDocPlugin action which parses all of the HTML files within a directory and comments all of the code within script tags. It should be complete soon -- stay tuned.