Javadoc, Java

  • 512 views
Uploaded on

Javadoc, Java

Javadoc, Java

More in: Education
  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
    Be the first to comment
    Be the first to like this
No Downloads

Views

Total Views
512
On Slideshare
0
From Embeds
0
Number of Embeds
1

Actions

Shares
Downloads
16
Comments
0
Likes
0

Embeds 0

No embeds

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
    No notes for slide

Transcript

  • 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 2008DSI 2007/08 (UDC) Documentando con Javadoc Marzo de 2008 1 / 22
  • 2. Documentando conContenido Javadoc DSI 2007/08 Contenido1 Introducci´n o Introducci´n o Tags Javadoc Extensi´n de Javadoc o2 Tags Javadoc Anotaciones Bibliograf´ ıa3 Extensi´n de Javadoc o4 Anotaciones5 Bibliograf´ ıa DSI 2007/08 (UDC) Documentando con Javadoc Marzo de 2008 2 / 22
  • 3. Documentando conMotivaci´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 conMotivaci´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 aJavadoc 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 conComentarios 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 conComentarios 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 conReglas 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 conTags 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 conTags 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 conDoclet & 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 conUMLGraph (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 conUMLGraph (y II) Javadoc DSI 2007/08class Tyre {} Contenidoclass 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 */ Anotacionesclass 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 conAnotaciones 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 conDefinici´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 conBibliograf´ ı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