How to _use_ a javadoc

Question

I have a very basic question about javadocs - I apologize in advance, I'm completely unfamiliar with the topic and can't find an answer on google.

I downloaded a certain implementation in java, and imported the downloaded projects in Eclipse. In the files that I needed, I found syntax that was unfamiliar to me, for example the following appeared before a function:

/**
 * Default implementation of the MarkovDecisionProcess<S, A> interface.
 * 
 * @param <S>
 *            the state type.
 */

It turns out that this kind of syntax is called a javadoc (?). My question is: How do I use this javadoc thing? Am I supposed to import the project into a separate one, or edit the given code? If so - how do I modify the @param syntax, for example?

Answer 1

Since there are already excellent answers that already describe the use of JavaDoc I won't repeat them and make it short: JavaDoc is for code documentation. That means it doesn't have any functional impact on the code it describes. It just describes what the method, class, constant etc. does. That has the advantage that you don't have to go through the code to find out what a method is for and what excactly it returns. IMHO it saves a lot of time.

As for changing the parameters of a method: You just change the code as you normally would without javaDoc. To prevent that the documentation says something else than the code actually does, you change the javaDoc according your changes on the method. JavaDoc normally looks like this:

    /**
     * Creates an instance of foo.
     * 
     * @param bar
     *            the size of bar
     * @return the created foo
     */
     public Foo createFoo(Bar bar)
     {
        //do something
        return new Foo(bar);
     }

As you can see the method desciption is followed by the parameter description of bar and then by the description what the method returns.

To add a new parameter you just have to add a new @param to the javaDoc:

    /**
     * Creates an instance of foo.
     * 
     * @param bar
     *            the size of bar
     * @param foobar
     *            <describe here what foobar is>
     * @return the created foo
     */
     public Foo createFoo(Bar bar, Foobar foobar)
     {
        //do something
        return new Foo(bar);
     }

Answer 2

Javadocs give information about your code. Eclipse (and probably every other IDE) uses it to give you information about the code you're currently writing.

This is just a picture of the little window that opens when I start typing System.cu.... The only function that matches it is currentTimeMillis, so that function is selected. To the right is another little window that contains the javadoc. It can show you a lot of information about what a function does and sometimes even how it works. It can also give you information about each parameter (that's what @param is for), the return value, any exceptions that might be thrown, and related functions/classes, etc.

Answer 3

Javadoc is a meta-language that allows automatic HTML generation to document your project.

You can find an example page on java.lang.Object here.

The official documentation and guidelines on how to use the javadoc tool are here.

If you're using an IDE, you can preview your javadoc.

In Eclipse for instance:

• Project
• Generate javadoc...
• This opens a wizard. After pressing Finish, you get a mini-site with your documentation, in the location of your choosing.

To get started, you can javadoc-comment your method, variable and class declarations through the /** ... */ syntax (or Alt-Shift-J in Eclipse to automatically generate a javadoc comment).

The @param and other options allow you to specify various aspects of your documentation.

You can also use raw HTML within your javadoc comments, and you have a number of javadoc generation parameters available both in the wizard and as command-line arguments.

Answer 4

The syntax is as follows:

@param      value    the explanation of the value.

This means your class has a parameter value. You don't really use this code expect when you are trying to understand what the class does. they are just like comment but you auto-generate the documentation in Eclipse using that code. Eclipse will read these comments and format into html files.

This is All the ways to generate javadoc in Eclipse