Diferencias

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

--- bloque3:javadoc [27/05/2019 20:23] – [Documentar las clases] Fernando Valdeón
+++ bloque3:javadoc [16/09/2024 20:53] (actual) – editor externo 127.0.0.1
@@ Línea 31: / 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**