Diferencias

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

--- bloque3:javadoc [25/02/2019 13:35] – [Tags o Etiquetas] Fernando Valdeón
+++ bloque3:javadoc [16/09/2024 20:53] (actual) – editor externo 127.0.0.1
@@ Línea 10: / Línea 10: @@
   * Documentación de cada constructor o método (especialmente los públicos) incluyendo:
     * 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 38: / Línea 88: @@
   * ''@since''
-**Documentación de constructores y métodos**
+  * **Documentación de constructores y métodos**
 En el comentario de cada método/constructor se debe explicar para que sirve.