Diferencias

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

--- bloque3:javadoc [05/03/2018 11:45] – Fernando Valdeón
+++ bloque3:javadoc [16/09/2024 20:53] (actual) – editor externo 127.0.0.1
@@ 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 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'' se encuentra 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.
@@ Línea 9: / Línea 9: @@
   * 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.
+    * nombre del constructor o método, descripción general, tipo de retorno, nombres y tipos de parámetros si los hay, 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.
+  * Las variables de instancia o de clase no se suelen documentar a nivel de javadoc. Solo las constantes públicas, si hubiera.
+**Es muy útil fijarse en el formato que tiene la documentación de métodos y constructores ya existentes en la API de Java**. Basta con situar el cursor del ratón encima de algún método o constructor.
 ==== Aspectos a tener en cuenta ====
@@ Línea 29: / Línea 31: @@
   * 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.
+==== Documentar métodos ====
+Si nos fijamos en la API de Java de alguna clase, p.e [[https://docs.oracle.com/javase/8/docs/api/java/lang/String.html|String ]] podemos tener una idea de cómo y qué se debe documentar.
+Aquí vemos la documentación del método //charAt()// de la clase //String//:
+<code java>
+/**
+ * Returns the {@code char} value at the
+ * specified index. An index ranges from {@code 0} to
+ * {@code length() - 1}. The first {@code char} value of the sequence
+ * is at index {@code 0}, the next at index {@code 1},
+ * and so on, as for array indexing.
+ *
+ * <p>If the {@code char} value specified by the index is a
+ * <a href="Character.html#unicode">surrogate</a>, the surrogate
+ * value is returned.
+ *
+ * @param      index   the index of the {@code char} value.
+ * @return     the {@code char} value at the specified index of this string.
+ *             The first {@code char} value is at index {@code 0}.
+ * @exception  IndexOutOfBoundsException  if the {@code index}
+ *             argument is negative or not less than the length of this
+ *             string.
+ */
+ public char charAt(int index) {
+    if ((index < 0) || (index >= value.length)) {
+            throw new StringIndexOutOfBoundsException(index);
+    }
+    return value[index];
+ }
+</code>
+Como vemos se indica una descripción del funcionamiento del método, qué representa cada parámetro, qué se espera devolver y si lanza alguna excepcion.
+A continuación se muestra como aparece en los documentos Javadoc generados:
+{{ :bloque3:string-javadoc.png?800 |}}
+Y aquí como se ve cuando accedo a la documentación del método en Eclipse:
+{{ :bloque3:javadoc-eclipse.png?800 |}}
+Como se ha indicado anteriormente, en la documentación de un método se debe indicar:
+  * Descripción de la funcionalidad del método
+  * Descripción de la finalidad de los parámetros
+  * Descripción de la finalidad del valor de retorno
+  * Excepciones, si es que lanza alguna
 ==== Tags o Etiquetas ====
-**Documentación de clases e interfaces**
+  * **Documentación de clases e interfaces**
 En el comentario de cada clase o interface se debe explicar para que sirve esa clase o interface.
@@ Línea 36: / Línea 86: @@
   * ''@author''
   * ''@version''
+  * ''@since''
-**Documentación de constructores y métodos**
+  * **Documentación de constructores y métodos**
-En el comentario de cada método se debe explicar para que sirve ese método.
+En el comentario de cada método/constructor se debe explicar para que sirve.
 Deben usarse al menos las etiquetas: