@) para Comentarios en Java Los siguientes parámetros también son utilizados al generar documentación para código Java:
| Elemento | Uso |
|---|---|
| @see <Nombre de la Clase> | Elemento utilizado para hacer referencia a otras Clases, genera un link HTML / XHTML hacia la Clase en cuestión. |
| @throws <Nombre de la Clase> | Empleado para indicar la Clase utilizada al generarse un Error. La definición de Clases para Errores será descrita en otra sección. |
| @deprecated | Este parámetro es utilizado para indicar que una Clase ha sido repuesta por otra más reciente; al ser indicado este parámetro en una Clase/Método el compilador (javac) generará un aviso, indicando que la Clase/Método ha sido repuesto. |
Además de los parámetros anteriores también es posible escribir lenguaje HTML / XHTML entre los elementos /** */ , lo anterior permite generar listas enumeradas, dar mayor estilo a la documentación y cualquier otro formato disponible en HTML / XHTML .
A continuación se ilustran dos Clases escritas anteriormente, con los respectivos comentarios para generar documentación:
| Clase Pantalla.java |
|---|
package com.osmosislatina.escritura;
/**
* Programa con métodos auxiliares para salto de linea
* y linea continua
* @author Juan Sanchez
* @author jsanchez@osmosislatina.com
* @version 1.3
*/
public class Pantalla {
/** Método para linea continua
* @params Un String
* @return Sin valor de retorno
* @exception exceptions Ningún error (Excepción) definida
*/
public static void sinSalto(String s) {
System.out.print(s);
}
/** Método para salto de linea
* @params Un String
* @return Sin valor de retorno
* @exception exceptions Ningún error (Excepción) definida
*/
public static void conSalto(String s) {
System.out.println(s);
}
}
|
| Clase MandaPantalla.java |
|---|
package com.osmosislatina.auxiliares;
import com.osmosislatina.escritura.*;
/**
* Programa para demostración de import en la Clase
* @author Juan Sanchez
* @author jsanchez@osmosislatina.com
* @version 1.6
* @see com.osmosislatina.escritura.Pantalla
*/
public class MandaPantalla {
/** Punto de Entrada único para Clase
* <ul>
* <li>Utiliza método sinsalto
* <li>Utiliza método consalto
* </ul>
* @param args Arreglo de String's
* @return Sin valor de retorno
* @exception exceptions Ningun error (Excepción) definida
*/
public static void main(String args[]) {
Pantalla primera = new Pantalla();
primera.conSalto("Esto es un renglón CON salto de linea");
primera.conSalto("Esta linea también tiene salto");
primera.sinSalto("Linea Continua");
primera.sinSalto("Linea Continua");
primera.conSalto("Esta linea si tiene salto!");
primera.sinSalto("Termina sin salto");
System.out.println(" Se termina el uso de funciones");
}
}
|
El comando javadoc posee una gran cantidad de parámetros para generar documentación, a continuación se describe su uso más básico:
$ mkdir docs $ javadoc -d docs/ -version -author -use *.java com/osmosislatina/escritura/*.java com/osmosislatina/auxiliares/*.java |
El primer paso antes de generar cualquier documentación Java es crear un directorio donde residirá la documentación, en este caso se ha generado un directorio llamado docs.
Posteriormente es invocado el comando javadoc con los siguiente parámetros:
-d docs: Indica el directorio donde será depositada la documentación (docs). -version: Implica que al ser generada la documentación sea desplegado el numero de versión, de ser definido en la Clase.-author : En caso de ser definido el parámetro autor, este aparecerá en la documentación.-use: Es el parámetro utilizado para indicar los directorios donde residen las Clases sobre las que será generada la documentación, en este caso se esta indicando el directorio presente (*.java) y los directorios com/osmosislatina/escritura y com/osmosislatina/auxiliares. Al terminar este proceso será generada la documentación de las distintas Clases dentro del directorio docs; para observar otros parámetros que puede tomar el comando javadoc basta ejecutar : javadoc -help.