1. Documentando con
Javadoc
DSI 2007/08
Contenido
Introducci´n
o
Documentando con Javadoc Tags Javadoc
Introducci´n
o Extensi´n de Javadoc
o
Anotaciones
Bibliograf´
ıa
Dise˜o de Sistemas Inform´ticos 2007/08
n a
MADS Group - Departamento de Computaci´n
o
Marzo de 2008
DSI 2007/08 (UDC) Documentando con Javadoc Marzo de 2008 1 / 22

2. Documentando con
Contenido Javadoc
DSI 2007/08
Contenido
1 Introducci´n
o Introducci´n
o
Tags Javadoc
Extensi´n de Javadoc
o
2 Tags Javadoc Anotaciones
Bibliograf´
ıa
3 Extensi´n de Javadoc
o
4 Anotaciones
5 Bibliograf´
ıa
DSI 2007/08 (UDC) Documentando con Javadoc Marzo de 2008 2 / 22

3. Documentando con
Motivaci´n (I)
o Javadoc
DSI 2007/08
¿A quienes interesa el c´digo fuente?
o
Contenido
Autores del propio c´digo
o Introducci´n
o
Otros desarrolladores del proyecto Tags Javadoc
Clientes de la API del proyecto
Extensi´n de Javadoc
o
¿Por qu´ documentarlo?
e Anotaciones
Mantenimiento Bibliograf´
ıa
Reutilizaci´n
o
¿Qu´ documentar?
e
Clases y paquetes
Obligatorio
Constructores, m´todos y atributos
e
/** Javadoc */
Fragmentos no evidentes
Conveniente
Bucles, algoritmos. . .
// una sola l´nea
ı
/* varias l´neas */
ı
DSI 2007/08 (UDC) Documentando con Javadoc Marzo de 2008 3 / 22

4. Documentando con
Motivaci´n (y II)
o Javadoc
DSI 2007/08
Generar documentacion de una API a mano es
Contenido
tedioso y propenso a errores
Introducci´n
o
- Gran cantidad de peque˜os detalles
n Tags Javadoc
- Sincronizaci´n de c´digo fuente y documentaci´n
o o o
Extensi´n de Javadoc
o
- Duplicidad de esfuerzos (tipos, nombres. . . )
Anotaciones
⇒ Combinar c´digo fuente con documentaci´n
o o Bibliograf´
ıa
+ Generar documentaci´n desde el c´digo
o o
+ La documentacion embebida en el codigo tiende a
ser m´s correcta
a
Javadoc
Genera documentaci´n en HTML
o
Usa la informaci´n de nombres, tipos. . .
o
Explicaciones adicionales y referencias cruzadas
Otras herramientas se apoyan en Javadoc para
ayudar a los desarrolladores (p.e. Eclipse)
DSI 2007/08 (UDC) Documentando con Javadoc Marzo de 2008 4 / 22

5. Documentando con
Comentarios Javadoc (I) Javadoc
DSI 2007/08
Comentarios con una sintaxis concreta, que se Contenido
ubican antes de las clases, interfaces, contructores, Introducci´n
o
metodos y atributos a documentar Tags Javadoc
Extensi´n de Javadoc
o
/** Anotaciones
* Bibliograf´
ıa
* Descripci´n principal (texto / HTML)
o
*
*
* Tags (texto / HTML)
*
*
*/
DSI 2007/08 (UDC) Documentando con Javadoc Marzo de 2008 5 / 22

6. Documentando con
Comentarios Javadoc (y II) Javadoc
DSI 2007/08
/**
* Returns the index of the first occurrence of the specified element in Contenido
* this vector, searching forwards from <code>index</code>, or returns -1 if
* the element is not found. Introducci´n
o
*
* @param o element to search for Tags Javadoc
* @param index index to start searching from
* @return the index of the first occurrence of the element in Extensi´n de Javadoc
o
* this vector at position <code>index</code> or later in the vector;
* <code>-1</code> if the element is not found Anotaciones
* @throws IndexOutOfBoundsException if the specified index is negative
Bibliograf´
ıa
* @see Object#equals(Object)
*/
public int indexOf(Object o, int index) ...
DSI 2007/08 (UDC) Documentando con Javadoc Marzo de 2008 6 / 22

7. Documentando con
Reglas elementales Javadoc
DSI 2007/08
La primera frase de cada comentario Javadoc debe Contenido
ser una frase resumen con una descripci´n concisa
o Introducci´n
o
y completa, terminada en punto, y seguida de un Tags Javadoc
espacio, tabulador o retorno de carro Extensi´n de Javadoc
o
Usar la etiqueta <code> para palabras clave y Anotaciones
Bibliograf´
ıa
nombres
Preferible el uso de la tercera persona
* Devuelve el ´ndice del primer elemento...
ı
* Devolvemos el ´ndice del primer elemento... ⇐ Evitar
ı
Empezar con un verbo la descripci´n de los m´todos
o e
Omitir el sujeto cuando es obvio
* @param peer nombre del peer
* @param peer par´metro con el nombre del peer ⇐ Evitar
a
DSI 2007/08 (UDC) Documentando con Javadoc Marzo de 2008 7 / 22

8. Documentando con
Tags Javadoc (I) Javadoc
DSI 2007/08
Palabras clave gestionadas de forma especial Contenido
Dos tipos, Introducci´n
o
Block tags Tags Javadoc
Ubicados despu´s de la descripci´n principal
e o Extensi´n de Javadoc
o
@tag Anotaciones
Inline tags Bibliograf´
ıa
Ubicados en la descripci´n principal o en las
o
descripciones de los block tags
{@tag}
/**
* ...
* @param id hash del objeto, calculado seg´n {@link #hash(Object)}
u
* ...
*/
@param, @return, @throws, @author, @version,
@see, @since. . .
Case sensitive
DSI 2007/08 (UDC) Documentando con Javadoc Marzo de 2008 8 / 22

9. Documentando con
Tags Javadoc (y II) Javadoc
DSI 2007/08
Clases, interfaces, constructores, m´todos, atributos
e
Contenido
⇒ *.java Introducci´n
o
Paquetes Tags Javadoc
⇒ package.html Extensi´n de Javadoc
o
Anotaciones
javadoc *.java
Generaci´n
o Bibliograf´
ıa
Ant
DSI 2007/08 (UDC) Documentando con Javadoc Marzo de 2008 9 / 22

10. Documentando con
@param name description Javadoc
DSI 2007/08
Aplicable a par´metros de constructores y m´todos
a e Contenido
Describe los par´metros del constructor/m´todo
a e Introducci´n
o
Tags Javadoc
name: id´ntico al nombre del par´metro
e a
Extensi´n de Javadoc
o
Anotaciones
/**
* Removes from this List all of the elements whose index is between Bibliograf´
ıa
* fromIndex, inclusive and toIndex, exclusive. Shifts any succeeding
* elements to the left (reduces their index).
* This call shortens the ArrayList by (toIndex - fromIndex) elements. (If
* toIndex==fromIndex, this operation has no effect.)
*
* @param fromIndex index of first element to be removed
* @param toIndex index after last element to be removed
*/
protected void removeRange(int fromIndex, int toIndex) {
...
}
DSI 2007/08 (UDC) Documentando con Javadoc Marzo de 2008 10 / 22

11. Documentando con
@return description Javadoc
DSI 2007/08
Aplicable a m´todos
e Contenido
Describe el valor de retorno del m´todo
e Introducci´n
o
Incluir descripci´n de valores de retorno especiales
o Tags Javadoc
Extensi´n de Javadoc
o
null
Anotaciones
...
Bibliograf´
ıa
/**
* Tests if this vector has no components.
*
* @return <code>true</code> if and only if this vector has
* no components, that is, its size is zero;
* <code>false</code> otherwise.
*/
public boolean isEmpty() {
return elementCount == 0;
}
DSI 2007/08 (UDC) Documentando con Javadoc Marzo de 2008 11 / 22

12. Documentando con
@throws type description Javadoc
DSI 2007/08
Aplicable a constructores y m´todos
e Contenido
Describe las posibles excepciones del Introducci´n
o
constructor/m´todo
e Tags Javadoc
Un @throws por cada posible excepci´n o Extensi´n de Javadoc
o
Anotaciones
Si es de ayuda para el usuario, tambi´n se pueden
e
Bibliograf´
ıa
documentar las unchecked exceptions
/**
* Parses the string argument as a signed decimal
* <code>long</code>. The characters in the string must all be
* decimal digits, except that...
*
* @param s a <code>String</code> containing the <code>long</code>
* representation to be parsed
* @return the <code>long</code> represented by the argument in
* decimal.
* @exception NumberFormatException if the string does not contain a
* parsable <code>long</code>.
*/
public static long parseLong(String s)
throws NumberFormatException {
....
DSI 2007/08 (UDC) Documentando con Javadoc Marzo de 2008 12 / 22

13. Documentando con
@see reference Javadoc
DSI 2007/08
Aplicable a clases, interfaces, constructores, Contenido
m´todos, atributos y paquetes
e Introducci´n
o
A˜ade enlaces de referencia a otras partes de la
n Tags Javadoc
documentaci´n
o Extensi´n de Javadoc
o
Anotaciones
Variantes,
Bibliograf´
ıa
@see string
@see <a href="URL">label</a>
@see package.class#member label
/**
*
* ...
*
* @see "Design Patterns: Elements of Reusable OO Software"
* @see <a href="http://www.w3.org/WAI/">Web Accessibility Initiative</a>
* @see String#equals(Object) equals
*/
public void method() {
...
}
DSI 2007/08 (UDC) Documentando con Javadoc Marzo de 2008 13 / 22

14. {@link package.class#member label} Documentando con
Javadoc
DSI 2007/08
Aplicable a clases, interfaces, constructores, Contenido
m´todos, atributos y paquetes
e Introducci´n
o
Equivalente a @see package.class#member label Tags Javadoc
Extensi´n de Javadoc
o
Inline tag
Anotaciones
No genera secci´n de referencias
o Bibliograf´
ıa
/**
* Returns the component at the specified index.
*
* This method is identical in functionality to the {@link #get(int)}
* method (which is part of the {@link List} interface).
*
* @param index an index into this vector
* @return the component at the specified index
* @throws ArrayIndexOutOfBoundsException if the index is out of range
* (<code>index < 0 || index >= size()</code>)
*/
public Object elementAt(int index) {
...
}
DSI 2007/08 (UDC) Documentando con Javadoc Marzo de 2008 14 / 22

15. {@inheritDoc} (I) Documentando con
Javadoc
DSI 2007/08
Impl´
ıcito
Copiado de documentaci´n
o Contenido
Expl´
ıcito Introducci´n
o
Impl´
ıcito (autom´tico)
a Tags Javadoc
Extensi´n de Javadoc
o
Cuando en un comentario Javadoc de un m´todo no
e
Anotaciones
se incluye una descripci´n general o un tag
o
Bibliograf´
ıa
@return, @param y/o @throws, la herramienta de
generaci´n de la documentaci´n toma la descripci´n
o o o
o el tag de la clase o interfaz de nivel superior
Para el caso del tag @throws solo se copia el tag de
la superclase si se trata de una checked exception
Expl´
ıcito
⇒ {@inheritDoc}
Aplicable a clases, interfaces, constructores y
m´todos
e
Inline tag
DSI 2007/08 (UDC) Documentando con Javadoc Marzo de 2008 15 / 22

16. {@inheritDoc} (y II) Documentando con
Javadoc
DSI 2007/08
Copia la documentaci´n del elemento de nivel
o
Contenido
superior inmediato
Introducci´n
o
⇒ Permite crear documentaci´n m´s general en las
o a Tags Javadoc
superclases y completarla en las subclases
Extensi´n de Javadoc
o
escribiendo alrededor del texto heredado
Anotaciones
Bibliograf´
ıa
/**
* (superclase) ...
*
* @throws NullPointerException if <code>dst</code> is <code>null</code>
*/
public void getChars(int srcBegin, int srcEnd, char dst[], int dstBegin) {
....
}
/**
* (subclase) ...
*
* @throws NullPointerException {@inheritDoc}
*/
public void getChars(int srcBegin, int srcEnd, char dst[], int dstBegin) {
DSI 2007/08 (UDC) Documentando con Javadoc Marzo de 2008 16 / 22

17. Documentando con
Doclet & Taglet API Javadoc
DSI 2007/08
Nuevos tags y salidas alternativas Contenido
Doclets Introducci´n
o
com.sun.javadoc.* Tags Javadoc
Definen el contenido y tipo de salida de la Extensi´n de Javadoc
o
herramienta Javadoc Anotaciones
-doclet Bibliograf´
ıa
UMLGraph (UMLGraphDoc), PDF Doclet. . .
Taglets
com.sun.tools.doclets.Taglet
Permiten incorporar nuevos block e inline tags a los
ya existentes en Javadoc
-tag
DSI 2007/08 (UDC) Documentando con Javadoc Marzo de 2008 17 / 22

18. Documentando con
UMLGraph (I) Javadoc
DSI 2007/08
“UMLGraph allows the declarative specification and Contenido
drawing of UML class and sequence diagrams” Introducci´n
o
Tags Javadoc
# Define the objects Extensi´n de Javadoc
o
object(O,"o:Toolkit");
Anotaciones
placeholder_object(P);
step(); Bibliograf´
ıa
# Activation and messages
active(O);
message(O,O,"callbackLoop()");
create_message(O,P,"p:Peer");
message(O,P,"handleExpose()");
active(P);
return_message(P,O,"");
inactive(P);
destroy_message(O,P);
inactive(O);
# Complete the lifeline of O
step();
complete(O);
DSI 2007/08 (UDC) Documentando con Javadoc Marzo de 2008 18 / 22

19. Documentando con
UMLGraph (y II) Javadoc
DSI 2007/08
class Tyre {} Contenido
class Engine {}
class Body {} Introducci´n
o
/**
* @composed 1 - 4 Tyre Tags Javadoc
* @composed 1 - 1 Engine
* @composed 1 - 1 Body Extensi´n de Javadoc
o
*/
Anotaciones
class Car {}
Bibliograf´
ıa
/** @hidden */
class Action {}
/**
* @stereotype container
* @tagvalue version 3.2
*/
class ActionQueue {
void add(Action a) {};
/** @tagvalue version 1.0 */
void add(Action a, int n) {};
void remove(int n) {};
/** @stereotype query */
int length() {};
/** @stereotype "helper functions" */
void reorder() {};
}
DSI 2007/08 (UDC) Documentando con Javadoc Marzo de 2008 19 / 22

20. Documentando con
Anotaciones Javadoc
DSI 2007/08
Introducidas en 1.5 Contenido
Metadatos del c´digo fuente
o Introducci´n
o
Posibles usos, Tags Javadoc
Extensi´n de Javadoc
o
Informaci´n para el compilador
o
Anotaciones
Informaci´n para herramientas de procesado
o
Procesamientos en tiempo de ejecuci´n
o Bibliograf´
ıa
Aplicables a clases, atributos, m´todos. . .
e
/**
* @deprecated explanation of why it was deprecated
*/
@Deprecated
public void deprecatedMethod() {
...
}
DSI 2007/08 (UDC) Documentando con Javadoc Marzo de 2008 20 / 22

21. Documentando con
Definici´n de anotaciones
o Javadoc
DSI 2007/08
import java.lang.annotation.*; // import this to use @Documented and @Retention Contenido
@Documented // Make the annotation appear in Javadoc generated doc Introducci´n
o
@Retention(RetentionPolicy.RUNTIME) // Make annotation available at runtime
@interface ClassPreamble { Tags Javadoc
String author(); Extensi´n de Javadoc
o
String date();
int currentRevision() default 1; Anotaciones
String lastModified() default "N/A";
String lastModifiedBy() default "N/A"; Bibliograf´
ıa
String[] reviewers(); // Note use of array
}
@ClassPreamble (
author = "John Doe",
date = "3/17/2002",
currentRevision = 6,
lastModified = "4/12/2004",
lastModifiedBy = "Jane Doe"
reviewers = {"Alice", "Bob", "Cindy"} // Note array notation
)
public class Generation3List extends Generation2List {
...
}
DSI 2007/08 (UDC) Documentando con Javadoc Marzo de 2008 21 / 22

22. Documentando con
Bibliograf´
ıa Javadoc
DSI 2007/08
[apt08] Annotation Processing Tool. Contenido
http://java.sun.com/j2se/1.5.0/docs/guide/apt/, 2008.
Introducci´n
o
[jav08] Javadoc 5.0 Tool.
Tags Javadoc
http://java.sun.com/j2se/1.5.0/docs/guide/javadoc/,
2008. Extensi´n de Javadoc
o
Anotaciones
[uml08] UMLGraph - Declarative Drawing of UML Diagrams.
http://www.umlgraph.org, 2008. Bibliograf´
ıa
[wri08] How to Write Doc Comments for the Javadoc Tool.
http://java.sun.com/j2se/javadoc/writingdoccomments/,
2008.
DSI 2007/08 (UDC) Documentando con Javadoc Marzo de 2008 22 / 22