I was just re-reading Mr. Ed’s Get Your Filthy Tags Out Of My Javadoc, Eugene, an article he posted way back in August. Mr Ed thumps the table and demands that Javadoc be simple, terse and free of HTML tags.
In my little world, Javadoc is what you look up when you don’t have access to the source. If you do have access to the source, you go and look at whatever class or method you are interested in and – hey presto – you have both Javadoc comments _and _the source. So I only ever seem to look up Javadoc for source-free1, third-party libraries.
But different people work in different ways, and some of my coworkers rely on Javadoc to understand the system they are building, even while it is being built. That is why I am thorough about putting Javadoc on all the code, and insist that others do likewise.
The one problem with my Javadoc is that I rarely, if ever, generate the HTML, meaning the finished result could be full of bad formatting and stupid errors (is it @return or @returns?) and I wouldn’t know.
So here is my Christmas Wish for Java. I would like some serious Javadoc support from my IDE. I’m thinking WYSYWIG, in-line Javadoc editting. That should make most formatting problems – like putting in paragraph tags – go away, and the rest bleeding obvious. Syntax checking should also be extended into the Javadoc comment to catch errors such as missing Javadoc or @param tags that don’t match the argument list.
The integration can’t be too far away – there are plenty of syntax checkers, and also some Javadoc editors already out there.
1 “source-free” being the opposite of “free-source”.
Comments
have you looked at the new javadoc support in Eclipse? auto-formats it for you, warns about unclosed tags etc. not exactly wysiwyg, but pretty good nonethess...
Sounds neat. But I still want it all.
Take a look at slickedit or the slickedit eclipse plug-in www.slickedit.com . They have a javadoc editor and a preview button that allows you to see how it looks.
I suspect that people who HTML-format their Javadoc have too much free time on their hands.
or 2 in a single JavaDoc comment.I never needed anything more than a
Intellij IDEA isn't the be-all and end-all for javadoc editing, but it's pretty darn nice. It'll do things like flagging @return vs @returns for you... syntax coloring it red as an error if you get it wrong. Heck, it'll even offer to correct it for you. Does some other stuff too.