*
* @author rluna
*
*/
/**
* 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.
*
*
* You can use html entities and tags, like <b>, <u>
*
* Portions of code can be inserted this way:
public class Circle extends Shape {
}
*
*
* And you can use all the html stuff you want to
* document your classes, methods, fields, and
* whatever you want.
*
* For instance, here is a table:
*
*
* one, two,
*
*
* three, and four
*
*
*
* @author rluna
*
*/
and here is the result:
{{ :java:11-javadoc-result.png?nolink& |}}
===== 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:
{{ :java:07_overview-placement.png?nolink& |}}
**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:
HERE CAN GO THE LICENSE, BECAUSE THIS DOESN'T APPEAR IN THE DOCUMENTATION.
THE FIRST SENTENCE OF THE OVERVIEW, UNTIL THE LAST POINT IS DIFFERENCED
FROM THE REST.
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
==== And how it looks like ====
{{ :java:08_overview.png?nolink& |}}
===== 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.
*
* 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:
{{ :java:06_package-info.png?nolink& |}}
===== 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:
{{ :java:09-hello-with-image.png?nolink& |}}
This would be done through the following javadoc comment:
/**
* This class outputs the classical message when run:
*
*
*
* @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:
{{ :java:10-where-is-directory-created.png?nolink& |}}
===== 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.
*
*
*
*
* @author some-text
* To set the author. Javadoc will put this info at the end.
*
*
* @deprecated some-text
* To inform that something is deprecated. Better put at the beginning
*
*
* {@code some-text}
* Is the equivalent to <code>some-text</code>.
* To insert code snippets in the comments.
*
*
* {@docRoot}
* To refer to the "root" of this javadoc. For
* instance, to refer an image: <img src="{@docRoot}/some-image.png">
*
*
* {@inheritDoc}
* 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.
*
*
* {@link package.class#member label}
* To create a link to another package, class, member. It
* will show a link with the text of the "label".
*
*
* {@linkplain package.class#member label}
* The same as link, but the link will be shown with
* normal font instead of code font.
*
*
* {@literal text}
* To include some text literally {@literal 3 < 5 > 7} will output:
* {literal 3 < 5 > 7}
*
*
* @param parameter-name description
* To describe a parameter. Put it in a single line.
*
*
* @return description
* Adds a "Returns" section in the description, and is
* used to better describe the return of some method.
*
*
* @see reference
* Adds a "See also" section in the description text. Forms
* of reference may be:
*
* - some-text - to refer to a book, for instance
*
- <a href="some-url">some-label</a> - to refer to a web page
*
- package.class#member label - to refer to another method or class
*
*
*
*
* @serial
*
*
* @serialField
*
*
* @serialData
*
*
* @since since-text
* This adds a "since" section in the documentation, with the
* specified since-text in it.
*
*
* @throws class-name description
* To indicate that this method trows a particular exception.
*
*
* {@value package.class#field}
* Use to refer to a value of a static field
*
*
* @version version-text
* To include a "version text" in the description.
*
*
*
* @author rluna
*
*/
{{ :java:12-javadoc-tags.png?nolink& |}}
===== 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:
{{ :java:01_project.png?nolink& |}}
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)
{{ :java:02_generation.png?nolink& |}}
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.
===== Last but not least: the eclipse project I've used for this example =====
{{:java:javadoctest.zip|}}