Gregg Sporar's Blog

Javadoc Hints

I've been browsing some open source projects lately and have been seeing a fair amount of source code without Javadoc comments. One of my favorite features in NetBeans IDE 6.0 is that it provides an editor hint that will create a Javadoc comment. That hint, however, is turned off by default.

This is best shown through examples. The file below is from the source for javac:

The IDE would be happy to add a Javadoc comment above line 56. And to repair the Javadoc comments above lines 69 and 78. But there are no hint icons in the margin to indicate that until I turn on that option:

Notice the dropdown list is set to Warning on Current Line which means the cursor has to be on the line that needs the Javadoc before the hint icon is displayed. So if I put the cursor on line 56 the icon appears:

If I click that icon with the mouse or press the Alt-Enter key on the keyboard the IDE will offer to insert the appropriate Javadoc comment. An option to reduce visual clutter by limiting the display of the hint to only when the cursor is on the line is very handy (not all tools are this flexible).

If, on the other hand, I want to see all Javadoc hints that are available regardless of the cursor position I can change the option to either Warning:

Or Error:

Comments

• It'd be nice, when adding features from other IDEs, to mention that you've finally got round to catching up and copying another feature that they've had for years... (this of course would apply if/when other IDEs copy features from Netbeans too). Give credit where it's due :-)

  Posted by: chris_e_brown on August 31, 2007 at 12:43 AM

• Well, I remember reading several times on the NetBeans site and on JavaLobby that the aim of the editor changes was to try and compete with IntelliJ's editor functionality. I trust that Gregg will correct me if I have erred here...

  What has driven these changes, alongside the editor being behind, is the ability of javac to now be used to semantic checking. Thus, if Java syntax changes happen on the back of Java 7, NetBeans will automatically pick these up with a minimum of effort. Given this it is hardly surprising that a fair number of features are appearing in NetBeans that are familiar to users of that IDE, or indeed Eclipse who copied lots of the from IntelliJ itself. It should also be pointed out that the scope for implementing this particular functionality in a radically different way is quite limited.

  As an aside, I distinctly remember a lot of early Eclipse-talk about a plug-in architecture without much reference to the fact that NetBeans already had such an architecture, particularly in articles of the kind above - a much more substantial feature than the one mentioned in the above article. However, did anyone not know that NetBeans wasn't there before them. Probably not, and those that didn't soon knew from the discussion that got provoked. Did anyone not know that NetBeans has lagged IntelliJ and Eclipse in editor functionality for some time? Probably not, and as I say, NetBeans has stated their aim is to compete with IntelliJ in terms of editor functionality. The leader in any given field as always is a target for the rest.

  Posted by: dynamite on August 31, 2007 at 03:59 AM

This work is licensed under a Creative Commons License.