Table of Contents
Javadoc made easy
Intro
This document is about adding javadoc content to your project. Because I've read the help and
Example of javadoc and its result
/**
* The first sentence appears separated from the
* rest of the document, so be careful with
* the first dot, who denotes the end of the
* first sentence.
*
* <p>
* <b>You can use html entities and tags, like <b>, <u></b></p>
* <p>
* Portions of code can be inserted this way:</p>
<pre>
public class Circle extends Shape {
}
</pre>
*
*<p>
* And you can use all the html stuff you want to
* document your classes, methods, fields, and
* whatever you want.</p>
* <p>
* For instance, here is a table:</p>
* <table>
* <tr>
* <td>one,</td><td>two,</td>
* </tr>
* <tr>
* <td>three,</td><td>and four</td>
* </tr>
* </table>
*
* @author rluna
*
*/
and here is the result:
Optional: Create an overview page for the entire application or set of packages
You can create a overview page of the entire application. To do this, just create a file called “overview.html” and put it where you want.
I've put it just under the “src” source file directory:
What to put in this file
Everything you think is relevant for the whole application or library you are documenting.
This page is not the first page of your documentation: on the contrary, it is only accessed trough the “overview” link who is in the upper or lower links of the page.
My overview page
Here goes an example of my overview page:
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> <html> <head> HERE CAN GO THE LICENSE, BECAUSE THIS DOESN'T APPEAR IN THE DOCUMENTATION. </head> <body> THE FIRST SENTENCE OF THE OVERVIEW, UNTIL THE LAST POINT IS DIFFERENCED FROM THE REST. <p> Here goes the rest of the explanation. Like a normal comment, you can put here link tags, and see tags if you need it. @since 1.0 @see java.lang.String @author PUT THE AUTHOR IF YOU WANT </body> </html>
And how it looks like
Optional: Document the package
You can create a file called “package-info.java” per package in order to document it. Put this file with the rest of java classes of the package.
This is the content of my file:
/**
* HERE GOES A SINGLE LINE THAT DESCRIBES THE PACKAGE; THE FINAL
* DOT SPECIFIES WHEN IT SHOULD END THIS FIRST STATEMENT, SO
* BEWARE USING DOTS INSIDE THE LINE.
* <p>
* And here is a more descriptive HTML content about the
* package. You can use {@link com.supermanhamuerto.test.Rectangle}
* for inserting links and see tags
*
* @author PUT HERE THE AUTHOR
* @since 1.0
* @see com.supermanhamuerto.test.Shape
* @version 1.0
*/
package com.supermanhamuerto.test;
And this is how it looks like:
Optional: where to put other files belonging to the docummentation
You can create a directory called “doc_files” to put every kind of file you might need for the documentation. You can create this directory for every directory package.
To include an image for the documentation
Let's say that in the documentation of our Hello class we need to add
an image:
This would be done through the following javadoc comment:
/** * This class outputs the classical message when run: * * <img src="../../../doc-files/example.png"> * * @author rluna * */
And you can add the image file example.png into the directory “doc-files”
in the package where the Hello class is located:
An explanation of the tags, in javadoc
As an example, I will document here the tags available in javadoc and the corresponding result of this documentation as a javadoc:
/** * Examples and usage of javadoc tags. * <br/> * <br/> * <table border="1" width="50%"> * <tr> * <td><b>@author</b> <i>some-text</i></td> * <td>To set the author. Javadoc will put this info at the end.</td> * </tr> * <tr> * <td><b>@deprecated</b> <i>some-text</i></td> * <td>To inform that something is deprecated. Better put at the beginning</td> * </tr> * <tr> * <td>{<b>@code</b> <i>some-text</i>}</td> * <td>Is the equivalent to <code>some-text</code>. * To insert code snippets in the comments.</td> * </tr> * <tr> * <td>{<b>@docRoot</b>}</td> * <td>To refer to the "root" of this javadoc. For * instance, to refer an image: <img src="{@docRoot}/some-image.png"></td> * </tr> * <tr> * <td>{<b>@inheritDoc</b>}</td> * <td>To inherit the documentation from its nearest class. Useful * to copy more general comments from its parent classes and then * copy to is derivated classes.</td> * </tr> * <tr> * <td>{<b>@link</b> <i>package.class#member</i> <i>label</i>}</td> * <td>To create a link to another package, class, member. It * will show a link with the text of the "label".</td> * </tr> * <tr> * <td>{<b>@linkplain</b> <i>package.class#member</i> <i>label</i>}</td> * <td>The same as link, but the link will be shown with * normal font instead of code font.</td> * </tr> * <tr> * <td>{<b>@literal</b> text}</td> * <td>To include some text literally {@literal 3 < 5 > 7} will output: * {literal 3 < 5 > 7}</td> * </tr> * <tr> * <td><b>@param</b> <i>parameter-name</i> <i>description</i></td> * <td>To describe a parameter. Put it in a single line.</td> * </tr> * <tr> * <td><b>@return</b> description</td> * <td>Adds a "Returns" section in the description, and is * used to better describe the return of some method.</td> * </tr> * <tr> * <td><b>@see</b> <i>reference</i></td> * <td>Adds a "See also" section in the description text. Forms * of reference may be: * <ul> * <li><i>some-text</i> - to refer to a book, for instance * <li><i><a href="some-url">some-label</a></i> - to refer to a web page * <li><i>package.class#member label</i> - to refer to another method or class * </ul> * </td> * </tr> * <tr> * <td><b>@serial</b></td> * <td></td> * </tr> * <tr> * <td><b>@serialField</b></td> * <td></td> * </tr> * <tr> * <td><b>@serialData</b></td> * <td></td> * </tr> * <tr> * <td><b>@since</b> <i>since-text</i></td> * <td>This adds a "since" section in the documentation, with the * specified since-text in it.</td> * </tr> * <tr> * <td><b>@throws</b> <i>class-name</i> <i>description</i></td> * <td>To indicate that this method trows a particular exception.</td> * </tr> * <tr> * <td><b>{@value</b> <i>package.class#field</i>}</td> * <td>Use to refer to a value of a static field</td> * </tr> * <tr> * <td><b>@version</b> <i>version-text</i></td> * <td>To include a "version text" in the description.</td> * </tr> * </table> * * @author rluna * */
To make javadoc to skip a directory
You can make javadoc to skip a directory simply by put a hyphen in this. This is usually made for instance to skip test source files.
Steps to generate a javadoc in eclipse
Project → generate javadoc:
Fill the information in the first step. Normally you will have to provide:
- select wich project (or package, or source file) do you want
the javadoc will generate documentation. Please attention to
this because * identify the location of the javadoc tool (if you don't know, probably you need more basic reading: it's in the JDk directory) * identify where do you want to store the html documents (in my case, I've selected the "doc" folder of the project, but it is better to use something called "javadoc" for clarity)
In the next step you will find a placeholder for the overview page, set this if it is your case.
The following steps are more or less straightforward.