What is a "javadoc utility" and good documentation?

[Ansmeon Kamen]

if your told to "include documentation readable by the javadoc utility suitable to the program's size" what is a "javadoc utility?.Would it be like Eclipse or whatever is "containing" Java?.Also could anyone give me an example of a Java program with excellent documentation please?.

[Jesper de Jong]

Javadoc is a tool that comes with the JDK, which you can use to generate documentation which looks like the standard Java API documentation.

It works like this: you put specially formatted comments above your classes, methods, interfaces etc., then run the Javadoc tool on your source code, and it then produces a directory containing HTML files.

See the documentation about Javadoc.

Javadoc comments start with /** and end with */. Here's a simple example:

/**
 * This is the documentation for the class Sandbox.
 */
public class Sandbox {

    /**
     * This is the {@code main} method, where execution of the program starts.
     * @param args Command line arguments.
     */
    public static void main(String[] args) {
        System.out.println(add(3, 5));
    }

    /**
     * Adds two numbers.
     *
     * @param a The first number.
     * @param b The second number.
     * @return The result of adding the two numbers.
     */
    public static int add(int a, int b) {
        return a + b;
    }
}

[Campbell Ritchie]

Also, you might find this thread helpful.

[Jj Taylor]

It's a really cool to use I've just started to understand it better, its definatly worth reading more about creating classes & methods yourself first so its easier to understand the classes that come with the SDK and you can be well away creating GUI's - if you wanted

My advice from starting out is Javas own tutorial was tricky to understand at first but I didnt know where to look compared to your step-by-step over advertised tutorial websites

After I found the right place on Javas own site things started becoming more clearer and in depth

http://docs.oracle.com/javase/tutorial/java/index.html

[Campbell Ritchie]

The Java tutorial has a few things in I don’t agree with, but it is by far the most comprehensive teaching resource I have ever seen for Java. I think in some places it might go too fast for beginners.