Javadoc tricks in Eclipse tagged:

Javadoc tricks in Eclipse

Posted by in Android, BlackBerry, Coding Tricks, How-to, J2ME

If you know me, you know I’m one of “those” developers who actually sees value in writing comments & javadoc in my code.

Part of that comes from my background of writing code that non-developer managers wanted to tweek/break (amazing how the financial world runs on Excel); part from working in a world-leading java dev house on massive projects. Not to forget such articles as , or my general tendancy to be rather CDO.

I like to think the main reason is when I come back to my code months (or a heavy weekend) later, I can still figure out what’s going on… this saves me time, making me a nicer guy to be around.

Javadoc is great for this type of thing, and Eclipse’s auto-complete functionality makes it really easy to write good documentation.

  1. To start a javadoc block for a procedure or field, put the cursor above the declaration and type /** ENTER. Eclipse will auto-complete the block for you, ready to type into.
  2. Javadoc’s power comes from being able to reference other classes from within the comment. This forms hyperlinks enabling the reader to find out more. To do this, start typing the name of the class you want to reference, then CTRL-SPACE. Eclipse should auto-complete the name, and add the link syntax around the class name e.g. typing MyCl CTRL-SPACE completes to {@link MyClass}.
  3. Another way is to add See also: references to the bottom of the comment. Use the @see tag to create a hyperlink. e.g. @see MyClass is displayed as See also: MyClass.
  4. Parameters & return values can be documented with the @param & @return tags. For personal docs, even I find these to be overkill most of the time, but for api or library code they are essential.
  5. To link to a member of a class, like MyClass.MyInner.helloWorld(String), the trick is to replace the last “.” character with a “#”. e.g. @see MyClass.MyInner#helloWorld(String)
  6. To link to a member of a class you are in, just type # CTRL-SPACE and let Eclipse prompt you with the available members to choose from.
  7. To deprecate a method, letting other devs know another method to use, then use the @deprecated tag with a short description e.g. @deprecated use {@link #anotherMethod()} instead.
  8. For the more CDO developers, reserved words like null, true, false can be surrounded by the <code><code> tags to make them look “right”. This is simple to do by just using CTRL-SPACE at the end of the word to auto-complete the tags.
  9. For the creative writers out there, remember this is HTML, so list tags, paragraph tags, line breaks & horizontal lines are all available.
  • Lastly, one thing I have found is that the auto-complete does not work directly after a “.”. So if you are trying to auto-complete the first word of a new sentence, just type a dummy character and a space before the word (don’t forget to delete that dummy char afterwards).

For more details on various tags allowed, the Oracle manual can be found here: How to Write Doc Comments for the Javadoc Tool.

hth, and good luck with that CDO…