Differences

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

--- java:javadoc [2012/10/13 16:25] – [An explanation of the tags, in javadoc] rlunaro
+++ java:javadoc [2022/12/02 21:02] (current) – external edit 127.0.0.1
@@ 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|}}