PDF de programación - Documentando con Javadoc - Introducción

Documentando con

Javadoc

DSI 2007/08

Contenido

Introducción

Tags Javadoc

Extensión de Javadoc

Anotaciones

Bibliografía

Documentando con Javadoc

Introducción

Diseño de Sistemas Informáticos 2007/08

MADS Group - Departamento de Computación

Marzo de 2008

DSI 2007/08 (UDC)

Documentando con Javadoc

Marzo de 2008

1 / 22

Contenido

1

Introducción

2 Tags Javadoc

3 Extensión de Javadoc

4 Anotaciones

5 Bibliografía

Documentando con

Javadoc

DSI 2007/08

Contenido

Introducción

Tags Javadoc

Extensión de Javadoc

Anotaciones

Bibliografía

DSI 2007/08 (UDC)

Documentando con Javadoc

Marzo de 2008

2 / 22

Documentando con

Javadoc

DSI 2007/08

Contenido

Introducción

Tags Javadoc

Extensión de Javadoc

Anotaciones

Bibliografía

Motivación (I)

¿A quienes interesa el código fuente?

Autores del propio código
Otros desarrolladores del proyecto
Clientes de la API del proyecto

¿Por qué documentarlo?

Mantenimiento
Reutilización

¿Qué documentar?



Obligatorio

Clases y paquetes
Constructores, métodos y atributos

/** Javadoc */

Conveniente

Fragmentos no evidentes
Bucles, algoritmos. . .

// una sola línea
/* varias líneas */

DSI 2007/08 (UDC)

Documentando con Javadoc

Marzo de 2008

3 / 22

Documentando con

Javadoc

DSI 2007/08

Contenido

Introducción

Tags Javadoc

Extensión de Javadoc

Anotaciones

Bibliografía

Motivación (y II)

Generar documentacion de una API a mano es
tedioso y propenso a errores

- Gran cantidad de pequeños detalles
- Sincronización de código fuente y documentación
- Duplicidad de esfuerzos (tipos, nombres. . . )
⇒ Combinar código fuente con documentación

+ Generar documentación desde el código
+ La documentacion embebida en el codigo tiende a

ser más correcta

Javadoc

Genera documentación en HTML

Usa la información de nombres, tipos. . .

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

Documentando con

Javadoc

DSI 2007/08

Contenido

Introducción

Tags Javadoc

Extensión de Javadoc

Anotaciones

Bibliografía

Comentarios Javadoc (I)

Comentarios con una sintaxis concreta, que se
ubican antes de las clases, interfaces, contructores,
metodos y atributos a documentar

/**

*
* Descripción principal (texto / HTML)
*
*
* Tags (texto / HTML)
*
*
*/

DSI 2007/08 (UDC)

Documentando con Javadoc

Marzo de 2008

5 / 22

Comentarios Javadoc (y II)

/**

* Returns the index of the first occurrence of the specified element in
* this vector, searching forwards from <code>index</code>, or returns -1 if
* the element is not found.
*
* @param o element to search for
* @param index index to start searching from
* @return the index of the first occurrence of the element in
*
*
* @throws IndexOutOfBoundsException if the specified index is negative
* @see
*/

this vector at position <code>index</code> or later in the vector;
<code>-1</code> if the element is not found

Object#equals(Object)

Documentando con

Javadoc

DSI 2007/08

Contenido

Introducción

Tags Javadoc

Extensión de Javadoc

Anotaciones

Bibliografía

public int indexOf(Object o, int index) ...

DSI 2007/08 (UDC)

Documentando con Javadoc

Marzo de 2008

6 / 22

Documentando con

Javadoc

DSI 2007/08

Contenido

Introducción

Tags Javadoc

Extensión de Javadoc

Anotaciones

Bibliografía

Reglas elementales

La primera frase de cada comentario Javadoc debe
ser una frase resumen con una descripción concisa
y completa, terminada en punto, y seguida de un
espacio, tabulador o retorno de carro
Usar la etiqueta <code> para palabras clave y
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
Omitir el sujeto cuando es obvio

* @param peer nombre del peer
* @param peer parámetro con el nombre del peer ⇐ Evitar

DSI 2007/08 (UDC)

Documentando con Javadoc

Marzo de 2008

7 / 22

Documentando con

Javadoc

DSI 2007/08

Contenido

Introducción

Tags Javadoc

Extensión de Javadoc

Anotaciones

Bibliografía

Tags Javadoc (I)

Palabras clave gestionadas de forma especial
Dos tipos,

Block tags

Ubicados después de la descripción principal
@tag

Inline tags

Ubicados en la descripción principal o en las
descripciones de los block tags
{@tag}

/**

* ...
* @param id hash del objeto, calculado según {@link #hash(Object)}
* ...
*/

@param, @return, @throws, @author, @version,
@see, @since. . .
Case sensitive

DSI 2007/08 (UDC)

Documentando con Javadoc

Marzo de 2008

8 / 22

Tags Javadoc (y II)

Clases, interfaces, constructores, métodos, atributos
⇒ *.java
Paquetes
⇒ package.html



Generación

javadoc *.java
Ant

Documentando con

Javadoc

DSI 2007/08

Contenido

Introducción

Tags Javadoc

Extensión de Javadoc

Anotaciones

Bibliografía

DSI 2007/08 (UDC)

Documentando con Javadoc

Marzo de 2008

9 / 22

@param name description

Aplicable a parámetros de constructores y métodos

Describe los parámetros del constructor/método
name: idéntico al nombre del parámetro

/**

* Removes from this List all of the elements whose index is between
* fromIndex, inclusive and toIndex, exclusive. Shifts any succeeding
* elements to the left (reduces their index).
* This call shortens the ArrayList by (toIndex - fromIndex) elements.
* 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) {

(If

...

}

Documentando con

Javadoc

DSI 2007/08

Contenido

Introducción

Tags Javadoc

Extensión de Javadoc

Anotaciones

Bibliografía

DSI 2007/08 (UDC)

Documentando con Javadoc

Marzo de 2008

10 / 22

@return description

Aplicable a métodos

Describe el valor de retorno del método
Incluir descripción de valores de retorno especiales

null
. . .

Documentando con

Javadoc

DSI 2007/08

Contenido

Introducción

Tags Javadoc

Extensión de Javadoc

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

@throws type description

Aplicable a constructores y métodos
Describe las posibles excepciones del
constructor/método
Un @throws por cada posible excepción
Si es de ayuda para el usuario, también se pueden
documentar las unchecked exceptions

/**

Documentando con

Javadoc

DSI 2007/08

Contenido

Introducción

Tags Javadoc

Extensión de Javadoc

Anotaciones

Bibliografía

The characters in the string must all be

* Parses the string argument as a signed decimal
* <code>long</code>.
* decimal digits, except that...
*
* @param
*
* @return
*
* @exception NumberFormatException
*
*/

parsable <code>long</code>.

s a <code>String</code> containing the <code>long</code>
representation to be parsed
the <code>long</code> represented by the argument in
decimal.

if the string does not contain a

public static long parseLong(String s)

throws NumberFormatException {
....

DSI 2007/08 (UDC)

Documentando con Javadoc

Marzo de 2008

12 / 22

Documentando con

Javadoc

DSI 2007/08

Contenido

Introducción

Tags Javadoc

Extensión de Javadoc

Anotaciones

Bibliografía

@see reference

Aplicable a clases, interfaces, constructores,
métodos, atributos y paquetes

Añade enlaces de referencia a otras partes de la
documentación
Variantes,

@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

{@link package.class#member label}

Aplicable a clases, interfaces, constructores,
métodos, atributos y paquetes
Equivalente a @see package.class#member label
Inline tag

No genera sección de referencias

Documentando con

Javadoc

DSI 2007/08

Contenido

Introducción

Tags Javadoc

Extensión de Javadoc

Anotaciones

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

Documentando con

Javadoc

DSI 2007/08

Contenido

Introducción

Tags Javadoc

Extensión de Javadoc

Anotaciones

Bibliografía

{@inheritDoc} (I)

Copiado de documentación

Implícito (automático)



Implícito
Explícito

Cuando en un comentario Javadoc de un método no
se incluye una descripción general o un tag
@return, @param y/o @throws, la herramienta de
generación de la documentación toma la descripción
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
Inline tag

DSI 2007/08 (UDC)

Documentando con Javadoc

Marzo de 2008

15 / 22

{@inheritDoc} (y II)

Copia la documentación del elemento de nivel
superior inmediato
⇒ Permite crear documentación más general en las

superclases y completarla en las subclases
escribiendo alrededor del texto heredado

/**