Generating Javadocs for XPages Applications

Home » 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 FilesJava 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"?>
<project default="javadoc">
<target name="javadoc">
<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="WebContentWEB-INFsrc" splitindex="true"
stylesheetfile="C:Workstylesheet.css" use="true" version="true">
</javadoc>
</target>
</project>

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:JavadocsMyProjectName.
  • 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 WebContentWEB-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.

Javadoc Example

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.

JRE

 

Once you’ve set up a JRE configuration, you can then select it on the Ant build configuration, apply it and run.

Ant

 

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!

6 thoughts on “Generating Javadocs for XPages Applications”

    1. Egor Margineanu

      Although I may be wrong, Domino designer extended Eclipse FileSystem to support jnsf:// paths. I guess it should be possible to extend common-vfs to support this.

      1. That would be useful. If I understand what you’re saying, that means you could use Apache Commons VFS to generate the Javadoc from the NSF itself. I’ll have to have a look, though getting this far stretched my abilities quite a bit!

  1. First, I am REALLY glad someone figured out how to do this from Designer. It has seemed a shame that this functionality just didn’t work despite Designer being based on Eclipse. Thank you!

    Second, cripes that seems like a lot of work!

    Finally, I don’t think my way is any less work, well, maybe a wee bit, but I just export the projects from DDE and then run JavaDoc from standard Eclipse. My way has downsides for sure but just throwing it out there.

    1. I did start with opening the on disk project in Eclipse and generating the Javadoc from there. But I wanted a way to do it from Designer. Once the JDK is installed and the JRE set up for it, running from Designer is pretty quick to set up. I’ve tended to just copy and paste the javadoc.xml, so then running it is easy.

      One thing I forgot to mention is that writing it to a Javadoc folder in the root means you can access it via .nsf/javadoc/index.html. Because it’s going to the NSF you need reader access in the ACL to access it.

  2. Egor Margineanu

    Other way would be to look for what triggers “Sync with On-Disk project” and extend it as Ant task, instead of trying to figure out how Domino Designer stores NSF file content.

Leave a Comment

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.

Scroll to Top