Generating Javadocs for XPages Applications
A few weeks ago Stephan Wissel blogged about securing XPages applications using an ANT script and, in a side note, also recommended generating a Javadoc at the same time.
For some time I’ve seen the Generate Javadoc… option on the Project menu of Domino Designer. If you’ve ever tried clicking on it, you’ll have found that it doesn’t work out of the box. So, encouraged by Stephan’s blog post, I dug deeper. A number of Eclipse-related articles on the web helped enormously, and I finally managed to get it working in a reusable method. The proof is this Javadoc of XPages OpenLog Logger, which I mentioned on yesterday’s OpenNTF webinar. So obviously the next step was to share how it’s done.
The key requirement is the Java SDK available from the Oracle website. I’ve downloaded the previous release, for Java SE 6 (found here) which I believe corresponds to the relevant version of Java used by XPages (Java agents use an older version). This just needs installing at C:\Program Files\Java and it’s refreshing to have a Java install that doesn’t try to install the accursed Ask toolbar! Once installed, you have the tool required to generate the Javadoc.
But Project > Generate Javadoc… still didn’t work for me. Part of this may be that this is standard Eclipse-based functionality and so requires physical files, so an on disk project and not the NSF. I’m yet to be able to generate a Javadoc directly from an NSF and I don’t think it’s possible.
So the next step is to create an on disk project of your NSF, if you haven’t already done it to enable source control. To create an on disk project, right-click on the application in the Applications Navigator of the XPages Perspective and select Team Development > Set up source control for this application…. I generally then just accept the defaults. If you already have an on disk project because you’re using source control, you don’t need to do this again.
I still was unable to use Project > Generate Javadoc… from the on disk project, but it did give me a big step forward. Because the process allows you to create an Ant script. Taking that script and modifying it a bit, I got an Ant script that worked. (An Ant script is an XML file that gives parameters for running an automated process.) To make things easy, I’ve got a standard Ant script called javadoc.xml that just needs a few minor changes after it’s put into your on disk project. Here is the code:
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<javadoc access="private" author="true" classpath=".classpath" destdir="Javadoc"
nodeprecated="false" nodeprecatedlist="false" noindex="false" nonavbar="false" notree="false"
packagenames="com.paulwithers.openLog" source="1.6" sourcepath="WebContent\WEB-INF\src" splitindex="true"
stylesheetfile="C:\Work\stylesheet.css" use="true" version="true">
So let’s walk through the code. The key functionality is in the javadoc element, so let’s cover the key attributes:
- access defines the lowest level properties and methods that will be outputted, in this case everything, because private is the lowest level. Other options are protected (probably not heavily used by newer XPages Java developers) or public. The last option would be the one to select if you were generating a high-level Javadoc of properties and methods accessible from SSJS.
- classpath points to the classpath file in the database relative to the javadoc.xml’s location.
- destdir is where you want to output the Javadoc. This can be relative to the javadoc.xml’s location or a literal path such as C:\Javadocs\MyProjectName.
- noindex, nonavbar and notree are boolean properties that affect the output. So with all set to false you get an index for the javadoc, a navigation bar and tree navigation.
- packagenames is the key attribute. This determines the packages for which Javadocs will be generated. This will change from database to database and is a comma-separated list.
- source is the source Java version, 1.6 mapping to the Java SE 6 version.
- sourcepath is the relative location for the folder containing the packages. I always use the folder name src. This is found in WebContent\WEB-INF and you can navigate to it in the on disk project of the Package Explorer. It needs to be a folder, not a package name.
- stylesheet is a stylesheet to use to style the Javadoc. You can use the standard Javadoc styling, but it’s a bit bland. A quick search on Google or your favourite search engine will fine numerous Javadoc stylesheets. I used the same one we use for the OpenNTF Domino API and if you find a Javadoc you like the look of, it’s usually called stylesheet.css in the same folder as the index.html. So you can copy the stylesheet and reuse it. The value can be a relative or literal path and I use the latter here.
So after you’ve made the relevant changes, right-click on the disk project and select New > Other > File. Call it javadoc.xml and save it to the root folder of the on disk project, alongside the plugin.xml.
Once the javadoc.xml is saved, right-click on it and select Run as > 3 Ant Build…. Don’t select 2 Ant Build or it will fail because it’s not set to run with the relevant JRE. Selecting 3 Ant Build… brings up a dialog box. Click on the JRE tab and select the JRE to use. The first time you do this, it will not yet be configured, so click on Installed JREs and add a JRE pointing to the JRE folder of the JDK you installed.
Once you’ve set up a JRE configuration, you can then select it on the Ant build configuration, apply it and run.
A Javadoc for the packages in packagenames found in the folder in sourcepath will now be outputted to the location in dest, styled using the stylesheet defined in the javadoc.xml. The progress will be logged to the Console view. When I’ve run it I’ve seen warnings logged for various packages that cannot be found. I think this is where it’s trying to create links to the relevant Javadocs. I don’t think that’s a critical issue. The key is that you now have Javadocs for all your properties and methods in all the classes in all the packages you defined. That’s a huge benefit, as far as I’m concerned, although writing a good Javadoc in itself seems an art. I still have more work to do on that, I suspect!