Diferencias

Muestra las diferencias entre dos versiones de la página.

--- bloque4:javadoc [02/03/2018 17:37] – Fernando Valdeón
+++ bloque4:javadoc [05/03/2018 11:44] (actual) – borrado Fernando Valdeón
@@ Línea 1: / Línea 1: @@
-====== JavaDoc - Documentación de Clases ======
-Javadoc es una utilidad incluida en el Kit de Desarrollo de Java (JDK) para la generación de documentación de APIs en formato HTML a partir de código fuente Java. La aplicación ''javadoc'' está incluida en la carpeta bin del directorio del JDK de Java, junto a otros programas como ''java'', ''javac'', ''jar'', etc.
-Javadoc es el estándar para documentar clases de Java. La mayoría de los IDEs para Java utilizan javadoc para generar de forma automática documentación de clases.
-===== Documentar las clases =====
-Veamos en primer lugar qué se debe incluir al documentar una clase:
-  * Nombre de la clase, descripción general, número de versión, nombre de autores.
-  * Documentación de cada constructor o método (especialmente los públicos) incluyendo:
-    * nombre del constructor o método, tipo de retorno, nombres y tipos de parámetros si los hay, descripción general, descripción de parámetros (si los hay), descripción del valor que devuelve.
-  * Las variables de instancia o de clase no se suelen documentar a nivel de javadoc. Solo las constantes, si hubiera.
-==== Aspectos a tener en cuenta ====
-  * La documentación para javadoc ha de incluirse entre símbolos de comentario que han de empezar con una barra y doble asterisco, y terminar con un asterisco y barra simple.
-<code java>
-/**
- *    Esto es un comentario para javadoc
- */
-</code>
-  * La ubicación del comentario le define a javadoc qué representa el comentario:
-    * si está incluido justo antes de la declaración de clase se considerará un comentario de clase,
-    * si está incluido justo antes de la signatura de un constructor o método se considerará un comentario de ese constructor o método.
-    * lo mismo en caso de una constante de clase.
-  * Para alimentar javadoc se usan ciertas palabras reservadas (tags) precedidas por el carácter "@", dentro de los símbolos de comentario javadoc. Si no existe al menos una línea que comience con @ no se reconocerá el comentario para la documentación de la clase.
-==== Tags o Etiquetas ====
-**Documentación de clases e interfaces**
-En el comentario de cada clase o interface se debe explicar para que sirve esa clase o interface.
-Deben usarse al menos las etiquetas:
-  * ''@author''
-  * ''@version''
-**Documentación de constructores y métodos**
-En el comentario de cada método se debe explicar para que sirve ese método.
-Deben usarse al menos las etiquetas:
-  * ''@param''
-una por argumento de entrada, indicando el tipo, y su funcionalidad
-  * ''@return''
-indicando el tipo y su funcionalidad, si el método no es void
-  * ''@exception ó @throws''
-una por tipo de Exception que se puede lanzar, solo si se lanzan (@exception y @throws se pueden usar indistintamente).
-===== Generar Javadoc en Eclipse =====
-Selecionamos el proyecto del que necesitamos obtener el Javadoc y vamos a ''Project -> Generate Javadoc''
-{{ :bloque4:generarjavadoc.jpg?200 |}}
-  * Si el campo de ''Javadoc command'' está vacío indicamos la ruta de nuestro javadoc.exe (En este caso puntual C:\Program Files\Java\jdk***\bin\javadoc.exe).
-  * Luego indicamos la carpeta de destino y seguimos el asistente.
-{{ :bloque4:dialogojavadoc.jpg?200 |}}
-  * Por defecto usaremos la ubicación estándar, que siempre es en nuestra __carpeta base__ del proyecto que contiene las clases que queremos documentar, en un nuevo directorio llamado ''doc''.
-  * Al pulsar finalizar, se habrá generado un directorio ''doc'' en la ruta específicada. Si abrimos el fichero ''index.html'' accederemos a la documentación de nuestro proyecto.
-JavaDoc es una aplicación que viene en el paquete JDK de Java, debemos tener ese paquete para poder usarlo y seleccionaremos el programa Javadoc.exe contenido en la carpeta bin (binarios) de la carpeta de nuestro jdk. Normalmente en "Archivos de programa /Java"
-----
-(c) {{date> %Y}} Fernando Valdeón