Javadoc en Java

Documenta un metodo con un comentario especial para que lectores y herramientas vean que recibe y que devuelve. En Yard.java, escribe un metodo add que toma int x e int y y devuelve su suma. Coloca un bloque /** */ justo encima de add. Dentro del bloque, describe el trabajo en una frase corta, luego etiqueta cada parametro con @param y el resultado con @return. En main, imprime add(10, 2). Compila con javac Yard.java y ejecuta java Yard. La pantalla debe mostrar 12. Deja las reglas de nombrado para la pagina siguiente — esta leccion es la forma del comentario de documentacion, no elegir nombres.

Coloca /** encima del metodo

La pagina de debugging imprimio valores para encontrar una suma incorrecta. Esta pagina escribe un comentario de documentacion encima de un metodo limpio. Abre Yard.java. Mantén el nombre de clase publica Yard. Borra etiquetas println de debug sobrantes que entierren la historia de documentacion, demos sobrantes de equals / ==, archivos horn de Machine sobrantes y cualquier Scanner de teclado. El programa no debe esperar que escribas. No necesitas linea import para esta demo.
Dentro de Yard, mantén un metodo pequeno y un main corto. El bloque de documentacion debe sentarse inmediatamente encima del metodo que describe. Una linea en blanco entre el */ de cierre y la linea del metodo esta bien. No escondas el bloque dentro de main. No pongas el bloque debajo del cuerpo del metodo.
Escribe la apertura del comentario con dos estrellas despues de la barra:
/**
Luego escribe una frase sencilla que diga que hace add. Luego escribe las etiquetas. Cierra con:
*/
El metodo en si sigue siendo Java ordinario:
static int add(int x, int y) {
return x + y;
}
Javadoc no cambia como funciona return. Le dice al lector que promete el metodo antes de leer cada linea del cuerpo.

Desde la carpeta que guarda Yard.java, ejecuta javac Yard.java. Cuando parentesis, llaves y puntos y coma coinciden, javac no escribe una linea propia. Luego ejecuta java Yard — no java Yard.java. Quita la extension .java del comando de ejecucion. Mantén una clase publica en el archivo para que el nombre coincida con Yard.
La pantalla muestra 12. Recorre la ejecucion una vez. Java empieza en Yard.main. La llamada add(10, 2) entra al metodo con x guardando diez e y guardando dos. La linea return entrega doce. System.out.println escribe ese numero. El bloque Javadoc no imprime por si solo. El bloque es para lectores y herramientas de documentacion. La prueba de principiante en esta pagina sigue siendo una ejecucion correcta tras un comentario claro.
Lee el bloque de comentario mientras miras la firma del metodo. La frase Adds two numbers. coincide con el trabajo de return x + y;. La linea @param x first number nombra el primer parametro. La linea @param y second number nombra el segundo parametro. La linea @return the sum of x and y nombra el resultado. Mantén la ortografia exacta de las etiquetas: @param y @return usan el signo @ y letras latinas.
Si aun ves x=10 e y=2 y luego 8 de un archivo de debugging, cambia al archivo de enseñanza de Javadoc y ejecuta java Yard otra vez. Si solo escribes // Adds two numbers. encima del metodo, escribiste un comentario de linea ordinario, no un bloque Javadoc. Mantén la forma de doble estrella /** para que el bloque sea documentacion, no una nota de una sola linea.
Di la regla en voz alta mientras miras la pantalla: documenta encima del metodo, etiqueta los parametros, etiqueta el retorno, luego compila y ejecuta para probar que el metodo sigue funcionando. No inventes lecturas largas de nombrado en esta pagina. El nombrado espera la siguiente leccion.

Lee el mapa de etiquetas

Una tabla corta guarda las tres piezas que escribiste en el comentario. La apertura /** */ marca un bloque de documentacion. @param describe un nombre de parametro. @return describe el valor que el metodo entrega. Mantén el nombre del metodo add y la llamada add(10, 2) para que la pantalla siga siendo un solo numero claro.
La tabla es el mapa corto de esta pagina. Primero colocas el bloque. Luego etiquetas entradas y salida. Luego verificas con javac y java Yard. Salta adivinar que cualquier estilo de comentario es Javadoc. Salta borrar el bloque antes de saber que el programa aun imprime 12.

Mantén la tabla al lado del archivo de enseñanza mientras editas. Señala @param x en el archivo, luego int x en la firma. Señala @param y, luego int y. Señala @return, luego la linea return. Ese juego de emparejar es toda la idea de principiante en una pasada. Las herramientas que leen Javadoc buscan esas etiquetas. Los lectores humanos usan el mismo mapa cuando el cuerpo del metodo crece despues.
Si demos de debugging sobrantes siguen cerca, guardalas como historia. Para esta leccion ejecuta el archivo de enseñanza de Javadoc para que la pantalla muestre 12 desde add, no lineas etiquetadas x= de una caza. Si javac se queja de clases publicas duplicadas, mantén solo Yard public.

Un // ordinario no es Javadoc

Una linea que empieza con // es una nota para quien lee el archivo. Es util, y este curso ya uso comentarios de linea antes. No es la forma de bloque de documentacion que enseña esta pagina. Javadoc para un metodo empieza con /** y termina con */. Las etiquetas @param y @return se sientan dentro de ese bloque.
Si colocas una cadena sencilla debajo del metodo despues de otras sentencias, esa cadena no es documentacion del metodo. El bloque de documentacion debe ser el comentario pegado encima del metodo. Mantén el bloque cerca de add. Mantén main libre de teatro falso de documentacion. La llamada en main sigue siendo una impresion normal de la suma devuelta.
Cuando el comentario esta mal pero el cuerpo del metodo esta bien, javac aun puede tener exito y java Yard aun puede imprimir 12. Por eso esta pagina te pide leer el comentario y la firma juntos, no solo la pantalla. La pantalla prueba la matematica. El comentario prueba que etiquetaste el contrato.

Comparado con impresiones de debugging

En la pagina de debugging, println respondio cuales eran realmente tus numeros cuando una suma parecia mal. En esta pagina, Javadoc responde que promete add antes de que un lector se meta en el cuerpo. Sigues compilando Yard.java y ejecutando java Yard. Los tokens nuevos son /**, @param y @return encima de un metodo.
Debugging uso salida ordinaria como linterna. Javadoc usa un comentario estructurado como etiqueta en la puerta del metodo. Cuando la etiqueta coincide con los parametros y el retorno, los lectores pierden menos tiempo adivinando. Cuando falta la etiqueta, el programa aun puede ejecutarse — el habito de documentacion sigue faltando.
Si un archivo de debugging sobrante sigue abierto, puedes ver x=10, y=2 y una suma vieja. Cambia al archivo de Javadoc para que main imprima add(10, 2) y el metodo lleve el bloque de documentacion. Mantén lecturas de estilo de nombrado fuera de esta pagina. Mantén la entrada de teclado fuera de esta pagina.

Antes del nombrado

Puedes colocar /** */ encima de add, etiquetar @param x, etiquetar @param y, etiquetar @return, y aun ver 12 despues de java Yard. Compila Yard.java y ejecuta java Yard para la demo guardada. El comentario dijo a los lectores el contrato. La pagina siguiente es nombrado, donde eliges nombres claros para lo que escribes.
Mantén la demo de add documentado para un par claro comentario-mas-ejecucion. Mantén archivos de debugging fuera de esta pagina cuando practiques documentacion. Mantén archivos de naming fuera de esta pagina hasta esa leccion. Esos tres habitos son el punto de control antes de avanzar. Cuando las etiquetas coinciden con la firma y la pantalla muestra 12, Javadoc hizo su trabajo en esta leccion y estas listo para el siguiente tema sobre nombrado.
Una ultima pasada por la carpeta: un Yard publico, un add documentado, una impresion en main, sin espera de teclado, sin reglas de nombrado forzadas. Ejecuta javac Yard.java y java Yard una vez mas en la demo que mantienes abierta. Si la pantalla sigue mostrando 12 y el comentario sigue encima de add con @param y @return, la forma de documentacion es solida y el curso puede pasar al nombrado en la pagina siguiente. Prefiere un bloque de documentacion claro en un metodo para que cada lectura ensene el mismo mapa.