I like javadoc. Heck, I like documentation. But I hate adding javadoc to my code. It’s tedious, and I can never remember all the tags. I don’t use an IDE so the formatting gets to me.
After attending a presentation at BJUG about software tools, I investigated jalopy and I liked what I found. Now, jalopy is more than just a javadoc comment inserter, but javadoc insertion was my primary use of the tool. It may be piss poor for code formatting and whatnot, but it was pretty good at inserting javadoc. I was using the ant plug-in and the instructions were simple and straight forward. It didn’t blow away any existing comments, and it didn’t munge any files, once I configured it correctly. And there are, make no mistake, lots of configuration options.
Jalopy has a slick Swing interface to set all these configuration options, and you can export your configuration to an XML file which can be referenced by others. This, along with the ant integration, make it a good choice for making sure that all code checked in by a team has similar code formatting.
However, I do have a few minor quibbles with this tool.
1. The default configuration of javadoc is busted. When you run it, it javadocs methods and classes just fine, but any fields are marked with “DOCUMENT ME!” when they should be commented out: “/** DOCUMENT ME! */”. This means that, with the default configuration, you can’t even run the formatter twice, since jalopy itself chokes on the uncommented “DOCUMENT ME!”.
2. The configuration file is not documented anywhere that I could find. I looked long and hard on the Internet, and only found one example of a jalopy configuration file here. And this is apparently just the default options exported to a file. I’ve put up a sample configuration file here which fixes problem #1. (This configuration is only for javadoc; it accepts all other defaults.)
3. The zip file that you download isn’t in its own directory. This means that when you unassumingly unzip it, it spews all over your current directory.
None of these are show stoppers, that’s for sure. If you’re looking for a free, open source java code formatting tool, jalopy is worth a close look.
Follow me on Twitter
Follow me on Blue Sky
Also check out the formatter that’s part of
the JRefactory project on sourceforge.
We used it on our last project (newstreets?)
at XOR/Seurat and it seemed very nice.
Has a JEdit plugin…
Tom,
When I last looked at jrefactory, which admittedly was a couple of years ago, the issue I had with it was that it insisted on keeping its configuration in $HOME/.Jrefactory, which made it hard to version control the code formatting settings. We ended up having to gimmick up some shell scripts which copied settings from the source tree to this directory before running the formatter.
Dan