javadoc

Documentando conJavadoc

DSI 2007/08

Contenido

Introduccion

Tags Javadoc

Extension de Javadoc

Anotaciones

Bibliografıa

Documentando con JavadocIntroduccion

Diseno de Sistemas Informaticos 2007/08

MADS Group - Departamento de Computacion

Marzo de 2008

DSI 2007/08 (UDC) Documentando con Javadoc Marzo de 2008 1 / 22


DSI 2007/08

Contenido

Introduccion

Tags Javadoc


Anotaciones

Bibliografıa

Contenido

1 Introduccion

2 Tags Javadoc

3 Extension de Javadoc

4 Anotaciones

5 Bibliografıa



DSI 2007/08

Contenido

Introduccion

Tags Javadoc


Anotaciones

Bibliografıa

Motivacion (I)

¿A quienes interesa el codigo fuente?

Autores del propio codigoOtros desarrolladores del proyectoClientes de la API del proyecto

¿Por que documentarlo?

MantenimientoReutilizacion

¿Que documentar?

Obligatorio

{Clases y paquetes

Constructores, metodos y atributos

/** Javadoc */

Conveniente

{Fragmentos no evidentes

Bucles, algoritmos. . .

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



DSI 2007/08

Contenido

Introduccion

Tags Javadoc


Anotaciones

Bibliografıa

Motivacion (y II)

Generar documentacion de una API a mano estedioso y propenso a errores

- Gran cantidad de pequenos detalles- Sincronizacion de codigo fuente y documentacion- Duplicidad de esfuerzos (tipos, nombres. . . )

⇒ Combinar codigo fuente con documentacion

+ Generar documentacion desde el codigo+ La documentacion embebida en el codigo tiende a

ser mas correcta

Javadoc

Genera documentacion en HTML

Usa la informacion de nombres, tipos. . .

Explicaciones adicionales y referencias cruzadas

Otras herramientas se apoyan en Javadoc paraayudar a los desarrolladores (p.e. Eclipse)



DSI 2007/08

Contenido

Introduccion

Tags Javadoc


Anotaciones

Bibliografıa

Comentarios Javadoc (I)

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

/**** Descripcion principal (texto / HTML)*** Tags (texto / HTML)***/



DSI 2007/08

Contenido

Introduccion

Tags Javadoc


Anotaciones

Bibliografıa

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

* this vector at position <code>index</code> or later in the vector;

* <code>-1</code> if the element is not found

* @throws IndexOutOfBoundsException if the specified index is negative

* @see Object#equals(Object)

*/

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



DSI 2007/08

Contenido

Introduccion

Tags Javadoc


Anotaciones

Bibliografıa

Reglas elementales

La primera frase de cada comentario Javadoc debeser una frase resumen con una descripcion concisay completa, terminada en punto, y seguida de unespacio, tabulador o retorno de carro

Usar la etiqueta <code> para palabras clave ynombres

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 descripcion de los metodos

Omitir el sujeto cuando es obvio

* @param peer nombre del peer

* @param peer parametro con el nombre del peer⇐ Evitar



DSI 2007/08

Contenido

Introduccion

Tags Javadoc


Anotaciones

Bibliografıa

Tags Javadoc (I)

Palabras clave gestionadas de forma especial

Dos tipos,Block tags

Ubicados despues de la descripcion principal@tag

Inline tags

Ubicados en la descripcion principal o en lasdescripciones de los block tags{@tag}

/**

* ...

* @param id hash del objeto, calculado segun {@link #hash(Object)}

* ...

*/

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

Case sensitive



DSI 2007/08

Contenido

Introduccion

Tags Javadoc


Anotaciones

Bibliografıa

Tags Javadoc (y II)

Clases, interfaces, constructores, metodos, atributos

⇒ *.java

Paquetes

⇒ package.html

Generacion

{javadoc *.java

Ant



DSI 2007/08

Contenido

Introduccion

Tags Javadoc


Anotaciones

Bibliografıa

@param name description

Aplicable a parametros de constructores y metodos

Describe los parametros del constructor/metodo

name: identico al nombre del parametro

/**

* 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. (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

Contenido

Introduccion

Tags Javadoc


Anotaciones

Bibliografıa

@return description

Aplicable a metodos

Describe el valor de retorno del metodo

Incluir descripcion de valores de retorno especiales

null. . .

/**

* 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

Contenido

Introduccion

Tags Javadoc


Anotaciones

Bibliografıa

@throws type description

Aplicable a constructores y metodos

Describe las posibles excepciones delconstructor/metodo

Un @throws por cada posible excepcion

Si es de ayuda para el usuario, tambien se puedendocumentar 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

Contenido

Introduccion

Tags Javadoc


Anotaciones

Bibliografıa

@see reference

Aplicable a clases, interfaces, constructores,metodos, atributos y paquetes

Anade enlaces de referencia a otras partes de ladocumentacion

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

Contenido

Introduccion

Tags Javadoc


Anotaciones

Bibliografıa

{@link package.class#member label}

Aplicable a clases, interfaces, constructores,metodos, atributos y paquetes

Equivalente a @see package.class#member label

Inline tag

No genera seccion de referencias

/**

* 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

Contenido

Introduccion

Tags Javadoc


Anotaciones

Bibliografıa

{@inheritDoc} (I)

Copiado de documentacion

{Implıcito

Explıcito

Implıcito (automatico)

Cuando en un comentario Javadoc de un metodo nose incluye una descripcion general o un tag@return, @param y/o @throws, la herramienta degeneracion de la documentacion toma la descripciono el tag de la clase o interfaz de nivel superiorPara el caso del tag @throws solo se copia el tag dela superclase si se trata de una checked exception

Explıcito⇒ {@inheritDoc}

Aplicable a clases, interfaces, constructores ymetodosInline tag



DSI 2007/08

Contenido

Introduccion

Tags Javadoc


Anotaciones

Bibliografıa

{@inheritDoc} (y II)

Copia la documentacion del elemento de nivelsuperior inmediato

⇒ Permite crear documentacion mas general en lassuperclases y completarla en las subclasesescribiendo alrededor del texto heredado

/**

* (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

Contenido

Introduccion

Tags Javadoc


Anotaciones

Bibliografıa

Doclet & Taglet API

Nuevos tags y salidas alternativas

Docletscom.sun.javadoc.*Definen el contenido y tipo de salida de laherramienta Javadoc-docletUMLGraph (UMLGraphDoc), PDF Doclet. . .

Tagletscom.sun.tools.doclets.TagletPermiten incorporar nuevos block e inline tags a losya existentes en Javadoc-tag



DSI 2007/08

Contenido

Introduccion

Tags Javadoc


Anotaciones

Bibliografıa

UMLGraph (I)

“UMLGraph allows the declarative specification anddrawing of UML class and sequence diagrams”

# Define the objects

object(O,"o:Toolkit");

placeholder_object(P);

step();

# 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

Contenido

Introduccion

Tags Javadoc


Anotaciones

Bibliografıa

UMLGraph (y II)

class Tyre {}

class Engine {}

class Body {}

/**

* @composed 1 - 4 Tyre

* @composed 1 - 1 Engine

* @composed 1 - 1 Body

*/

class Car {}

/** @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

Contenido

Introduccion

Tags Javadoc


Anotaciones

Bibliografıa

Anotaciones

Introducidas en 1.5

Metadatos del codigo fuente

Posibles usos,

Informacion para el compiladorInformacion para herramientas de procesadoProcesamientos en tiempo de ejecucion

Aplicables a clases, atributos, metodos. . .

/**

* @deprecated explanation of why it was deprecated

*/

@Deprecated

public void deprecatedMethod() {

...

}



DSI 2007/08

Contenido

Introduccion

Tags Javadoc


Anotaciones

Bibliografıa

Definicion de anotaciones

import java.lang.annotation.*; // import this to use @Documented and @Retention

@Documented // Make the annotation appear in Javadoc generated doc

@Retention(RetentionPolicy.RUNTIME) // Make annotation available at runtime

@interface ClassPreamble {

String author();

String date();

int currentRevision() default 1;

String lastModified() default "N/A";

String lastModifiedBy() default "N/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

Contenido

Introduccion

Tags Javadoc


Anotaciones

Bibliografıa

Bibliografıa

[apt08] Annotation Processing Tool.http://java.sun.com/j2se/1.5.0/docs/guide/apt/, 2008.

[jav08] Javadoc 5.0 Tool.http://java.sun.com/j2se/1.5.0/docs/guide/javadoc/,2008.

[uml08] UMLGraph - Declarative Drawing of UML Diagrams.http://www.umlgraph.org, 2008.

[wri08] How to Write Doc Comments for the Javadoc Tool.http://java.sun.com/j2se/javadoc/writingdoccomments/,2008.


http://java.sun.com/j2se/1.5.0/docs/guide/apt/

http://java.sun.com/j2se/1.5.0/docs/guide/javadoc/

http://www.umlgraph.org

http://java.sun.com/j2se/javadoc/writingdoccomments/

javadoc

Documents

documentando conjavadocdsi

udc documentando

javadoc marzo

param index index

param fromindex index

param toindex index

specified index

param o element