Getting started with the javadoc

If you are using eclipse, working with javadoc is pretty easy. It's not that complicated using the command line either, personally I'm an addict to the command line, but I didn't bother too much with generating the javadoc using it since I tried already and I failed miserably. I had a problem when trying to set the classpath, since there was a lot of dependencies to include. I should have written an ant script, but I was too lazy. All programmers are :). So, I just chose the easy way for once, selecting project > generate javadoc... You have then to go through the usual straightforward process, choosing some options and then next, next.

java heap space configuration

And don't forget to configure the JVM heap space, especially when you have a big project with a lot of comments in it. This way, the javadoc will be generated a lot faster, and you won't be at the risk of having an error with heap space.
My advice is, don't forget to document well you code. A good code is a self documenting code. Compare:

int x;
String y;

and

int hitPoints;
String playerName

A lot better, isn't it?
And if you have a self documenting code like the last one, when you put comments to explain it, if you are not going to add some value to the explanation, it's better to leave it as it is.

/** calcualte the number of the likes */ 
public int calculateNumberOfLikes()

That's what I would call a waste of time. Who'd do that anyway, well, more people than you think, not all people have learnt to program the way programming should really be.

/** This function calculates the number of the likes of a friend.
 * 
 * This function calls an FQL query which determines the pages a friend likes,
 * and calculates the number of times he liked an item in that page
 *
 * @author someone 
 */ 
public int calculateNumberOfLikes()

This is just a little example to show the forms a javadoc comment has. The first sentece is a summary of what the function does. Then a more detailed description, then some javadoc-specific tags about the purpose of the function, we can add html tags to this description in order to format it the way we want. There is a lot of tags to know about, which can give us a lot of information about a function, a class or a variable. So, it's good to have the habit of well documenting our code, cause we are not the only ones that work in our code, and we can make others win a lot of time by making it easier for them to understand our code. And in case of a solo programmer working on his hobby project, you'll eventually end up coming back to the code you wrote after some months, and then, there is no telling how much of your code you will remember and how much time you will waste because of a poor documented code.