Cómo usar javadoc para documentar sus clases
Un paso queda antes de que pueda salir a bolsa con su nueva biblioteca de clases caliente o aplicación: la preparación de la documentación para sus clases. Afortunadamente, Java proporciona una herramienta llamada JavaDoc que puede crear automáticamente documentación basada en HTML de fantasía basado en los comentarios en los archivos de origen.
Video: [Clase en vivo] ¿Cómo generar documentación en Java? javadoc [2/3]
Todo lo que tiene que hacer es añadir un comentario para cada clase pública, campo y método- continuación, ejecute los archivos de origen a través de la Javadoc mando- voilá! usted tiene la documentación de aspecto profesional, basada en la web para sus clases.
La adición de comentarios JavaDoc
La regla básica para la creación de los comentarios JavaDoc es que comienzan con / ** y terminar con * /. Puede colocar comentarios JavaDoc en cualquiera de los tres lugares diferentes en un archivo de origen:
Inmediatamente antes de la declaración de una clase pública
Inmediatamente antes de la declaración de un campo público
Inmediatamente antes de la declaración de un método público o constructor
Un comentario Javadoc puede incluir texto que describe la clase, un campo o método. Cada línea subsiguiente de un comentario de varias líneas JavaDoc por lo general comienza con un asterisco. JavaDoc ignora esta asterisco y cualquier espacio en blanco entre él y la primera palabra de la línea.
El texto en un comentario Javadoc puede incluir el formato HTML, si desea aplicar formato de lujo. Usted debe evitar el uso de etiquetas de título (y así sucesivamente), ya que crea los JavaDoc, y sus etiquetas de título simplemente confundir las cosas. Pero se puede usar etiquetas para negrita y cursiva (y ) O para formatear ejemplos de código (utilice el
Además, puede incluir especial etiquetas doc que proporcionan información específica utilizada por JavaDoc para dar formato a las páginas de documentación.
| Etiqueta | Explicación |
|---|---|
| @autor | Proporciona información sobre el autor, por lo general la autor&rsquo-s nombre, dirección de correo electrónico, información del sitio web, y por lo tanto en. |
| @versión | Indica el número de versión. |
| @ya que | Se utiliza para indicar la versión con la que esta clase, un campo o se añadió método. |
| @param | Proporciona el nombre y la descripción de un método o constructor. |
| @regreso | Proporciona una descripción de un método&rsquo-s valor de retorno. |
| @throws | Indica excepciones lanzadas por un método o constructor. |
| @obsoleto | Indica que está en desuso de la clase, un campo o método y shouldn&utilizar rsquo-t. |
Para darle una idea de cómo se usan normalmente los comentarios JavaDoc, echa un vistazo a este código.
Video: [Clase en vivo] 1.- toString() y javaDoc
Tenga en cuenta que para el Empleado clase para compilar, también debe proporcionar una clase llamada Dirección, lo que representa una dirección de calle. La siguiente clase simple será suficiente:
Dirección clase pública implementa Cloneable {public String cadena calle-public String ciudad-estado entre entidades públicas cadena zipCode-}Con este código, muestra una clase de empleados con los comentarios JavaDoc.
paquete com.lowewriter.payroll - / ** Representa un empleado * @author Doug Lowe * * @author LoweWriter.com @version 1.5 * 1.0 * @since / public class Empleado {private String salario doble cadena primerNombre-privada lastName-privada. - / ** Representa la dirección del empleado * / dirección dirección pública -.. / ** Crea un empleado con el nombre especificado * @param apellido apellido del empleado * @param primerNombre el primer nombre del empleado * / public empleado (String.. lastName, cadena primerNombre) {this.lastName = lastName-this.firstName = primerNombre-this.address = nueva Dirección () -} / ** Obtiene el apellido del empleado * @return Una cadena que representa la última * el nombre del empleado. *. / cadena getLastName pública () {return this.lastName -} / ** Establece el apellido del empleado * @param apellido * Una cadena que contiene el apellido del empleado * / public void setLastName (String lastName) {this.lastName = lastName.. -} / ** Obtiene el primer nombre del empleado * @return Una cadena que representa la primera * nombre * / public string getFi del empleado.. rstName () {return this.firstName -}.. / ** Establece el primer nombre del empleado * @param primerNombre una cadena conteniendo el * nombre del empleado * / public void setFirstName (String primerNombre) {this.firstName = primerNombre -} / ** Obtiene el sueldo del empleado * @return Un doble que representa el sueldo del empleado * / public double getSalary () {return this.salary -}.. / ** Establece el sueldo del empleado * @param lastName Un doble que contiene * sueldo del empleado. . * / public void setSalary (doble sueldo) {this.salary = sALARIO}}Usando el comando javadoc
los Javadoc comando tiene un par de docenas de opciones que se pueden establecer, por lo que es un comando complicado de usar. Sin embargo, puede ignorar todas estas opciones para crear un conjunto básico de páginas de documentación. Sólo especifique la ruta completa de todos los archivos de Java que desea crear documentación para, de esta manera:
Javadoc comlowewriterpayroll * .java
los Javadoc comando crea las páginas de documentación en el directorio actual, por lo que es posible que desee cambiar al directorio en el que desea que las páginas que residen en primer lugar.
Para obtener información más completa sobre el uso de este comando, consulte la documentación Javadoc en el sitio web de Sun.
Visualización de páginas JavaDoc
Después de ejecutar el comando javadoc, puede acceder a las páginas de documentación, comenzando con la página index.html. Para mostrar rápidamente esta página, simplemente escriba index.html en el símbolo del sistema después de ejecutar el comando javadoc. O puede iniciar el navegador, vaya al directorio donde ha creado las páginas de documentación, y abra la página index.html.
Si cree que esta página parece familiar, es porque se ha creado la documentación de la API de Java utilizando JavaDocs. Por lo que ya debe saber cómo encontrar su camino en estas páginas.
Para mirar la documentación para una clase, haga clic en el enlace del nombre de la clase. Una página con la documentación completa para la clase aparece. JavaDocs genera esta página del archivo de origen.
