Doclipse

A JavaDoc Tag Plug-in for Eclipse

Cedric Beust

Created June 15th, 2004
Last modified July 21st, 2004

Introduction

Doclipse is an Eclipse plug-in to help you write Java source files with Javadoc tags, either for documentation purposes or to be processed by a tool such as EJBGen or XDoclet.  New tags can be added to the plug-in by writing XML files defining the new tags and their attributes.

Downloading Doclipse

The current version of the plug-in can be downloaded here.

Mailing-list

A mailing-list to discuss Doclipse has been created here.

Installing Doclipse

Unzip the distribution in the plugins/ directory of your eclipse installation.  You can verify that the plug-in is installed by launching Eclipse and opening the Windows / Preferences menu.  You should see an item "Doclipse" in the tree on the left-hand side, which you can click.  This page is explained below.

Using the completion

Doclipse ships with over twenty definition files, among which:

You can use completion right away even if you haven't added any new definition file yourself.  Just type an "@" and "Control-space" to trigger auto-completion.  You will see the regular Javadoc completions (@author, etc..) and also the new ones added by Doclipse.

These choices will narrow down as you type in the usual way.

Completion can happen at three different places:

The choices offered for completion depend on a definition file, which is described below.

The Preference Page

Doclipse ships with a few definition files but you can add your own as well.  In order to do that, you need to invoke the Preferences page for Doclipse:

The first group called "Internal files" shows you which definition files are shipped with Doclipse.  The second group, "External files", is where you tell Doclipse where it should find additional definition files.  Doclipse will read the directory indicated in the textfield and it will parse all the XML files that it can recognize in it.  Also, you can force Doclipse to reread that directory in case you made a modification in your definition file and you want it to be recognized by Eclipse.

Each definition file can be individually deselected, so that you can get rid of completions you don't need.  This is useful if the plug-in contains files for software you never use, or if you want to use a definition file that is more recent than the one that ships with Doclipse.  In this case, install the newer file in your external directory and deselect the file in the internal directory group.

For your convenience, the buttons "Select all" and "Deselect all" allow you to quickly check and uncheck all the files.

The Definition File

Doclipse definition files are written in XML and the exact doctype can be found inside the distribution.  Here is a quick example to get you started.

Let's assume we want to add a tag @code-review with two attributes:  a reason, which is required, and the author of the review, which is optional.  Here is the XML file:

<?xml version="1.0" encoding="UTF-8"?>

<doclipse>
  <description>Code review tags</description>
  <tag name="@code-review" target="method"
            doc="Code review tags.">
    <attribute name="reason" required="true"
            doc="The reason for this code review."/>
    <attribute name="author"
            doc="The author of this code review."/>
    <attribute name="urgent" allowed="yes no"
            doc="Should this be fixed soon?" />
  </tag>
</doclipse>

This file contains

Once you have created your file, save it in a directory, go to the preference pages and specify the directory where you saved it (or simply push "Reread this directory" if it was already saved there).  You should now see your new file listed in the "External files" group:

The new completion is now available:

and when you accept it, Doclipse will automatically insert all the required attributes (only "reason" in this example) so you don't forget to define them:

 

In the definition file above, we specified that the attribute "urgent" could have only two values: "yes" and "no".  Here is what happens when you are about to type the value for this attribute:

 

 


Back to my home page.

Or check out some of my other projects: