User Tools

Site Tools


java:javadoc

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
java:javadoc [2012/10/13 18:26]
rlunaro [Steps to generate a javadoc in eclipse]
java:javadoc [2014/12/24 10:42] (current)
Line 1: Line 1:
 +====== 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 =====
 +
 +<code javadoc>
 +/**
 + * 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 &​lt;​b&​gt;,​ &​lt;​u&​gt;</​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
 + *
 + */
 +</​code>​
 +
 +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:
 +
 +<code html>
 +<​!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>​
 +</​code>​
 +
 +==== 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: 
 +
 +<​code>​
 +/**
 + * 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;​
 +</​code>​
 +
 +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: ​
 +
 +<code javadoc>
 +/**
 + * This class outputs the classical message when run:
 + ​* ​
 + * <img src="​../​../​../​doc-files/​example.png">​
 + ​* ​
 + * @author rluna
 + *
 + */
 +</​code>​
 +
 +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: ​
 +
 +<code html>
 +/**
 + * Examples and usage of javadoc tags. 
 + * <br/>
 + * <br/>
 + * <table border="​1"​ width="​50%">​
 + * <tr>
 + * <​td><​b>&#​064;​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>&#​064;​deprecated</​b>​ <​i>​some-text</​i></​td>​
 + * <​td>​To inform that something is deprecated. Better put at the beginning</​td>​
 + * </tr>
 + * <tr>
 + * <​td>​{<​b>&#​064;​code</​b>​ <​i>​some-text</​i>​}</​td>​
 + * <​td>​Is the equivalent to &​lt;​code&​gt;​some-text&​lt;/​code&​gt;​. ​
 + * To insert code snippets in the comments.</​td>​
 + * </tr>
 + * <tr>
 + * <​td>​{<​b>&#​064;​docRoot</​b>​}</​td>​
 + * <​td>​To refer to the "​root"​ of this javadoc. For 
 + * instance, to refer an image: &lt;img src="​{&#​064;​docRoot}/​some-image.png"&​gt;</​td>​
 + * </tr>
 + * <tr>
 + * <​td>​{<​b>&#​064;​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>&#​064;​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>&#​064;​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>&#​064;​literal</​b>​ text}</​td>​
 + * <​td>​To include some text literally {&#​064;​literal 3 < 5 > 7} will output:
 + * {literal 3 < 5 > 7}</​td>​
 + * </tr>
 + * <tr>
 + * <​td><​b>&#​064;​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>&#​064;​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>&#​064;​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>&​lt;​a href="​some-url"&​gt;​some-label&​lt;/​a&​gt;</​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>&#​064;​serial</​b></​td>​
 + * <​td></​td>​
 + * </tr>
 + * <tr>
 + * <​td><​b>&#​064;​serialField</​b></​td>​
 + * <​td></​td>​
 + * </tr>
 + * <tr>
 + * <​td><​b>&#​064;​serialData</​b></​td>​
 + * <​td></​td>​
 + * </tr>
 + * <tr>
 + * <​td><​b>&#​064;​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>&#​064;​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>​{&#​064;​value</​b>​ <​i>​package.class#​field</​i>​}</​td>​
 + * <​td>​Use to refer to a value of a static field</​td>​
 + * </tr>
 + * <tr>
 + * <​td><​b>&#​064;​version</​b>​ <​i>​version-text</​i></​td>​
 + * <​td>​To include a "​version text" in the description.</​td>​
 + * </tr>
 + * </​table>​
 + ​* ​
 + * @author rluna
 + *
 + */
 +
 +</​code>​
 +
 +
 +{{ :​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|}}
 +
  
java/javadoc.txt ยท Last modified: 2014/12/24 10:42 (external edit)