Cómo usar javadoc para documentar sus clases

Un paso permanece antes de poder salir a bolsa con su biblioteca de clases nuevo 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.

Todo lo que tienes 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 mandamiento voil # 225-! usted tiene la documentación de aspecto profesional, basado en la web para sus clases.

Adición de comentarios JavaDoc

La regla básica para la creación de los comentarios JavaDoc es que comienzan con / ** y terminar con * /. Usted 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, 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 en la línea.

El texto en un comentario JavaDoc puede incluir código HTML si desea aplicar el formato de lujo. Usted debe evitar el uso de etiquetas de título (

y así sucesivamente), porque JavaDoc crea esos, y sus etiquetas de título acaba de confundir las cosas. Pero usted puede usar etiquetas para negrita y cursiva ( y ) O para formatear ejemplos de código (utilice el
etiqueta).

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.

TagExplicación
authorProporciona información sobre el autor, por lo general el nombre de theauthor, dirección de correo electrónico, información del sitio web, y pronto.
versionIndica el número de versión.
@desdeSe utiliza para indicar la versión con la que se añadió esta clase, campo, ormethod.
paramProporciona el nombre y la descripción de una orconstructor método.
@regresoProporciona una descripción del valor de retorno de un método.
throwsIndica excepciones que se tiran por un orconstructor método.
deprecatedIndica que la clase, campo o método está en desuso andshouldn't usarse.

Para que te hagas una idea de cómo se utilizan normalmente comentarios JavaDoc, echa un vistazo a este código.

Tenga en cuenta que para la 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 public class implementa Cloneable {public String String-calle pública-ciudad public String-pública estatal Cadena zipCode-}

Este código muestra una clase de empleados con comentarios JavaDoc.

paquete com.lowewriter.payroll - / ** Representa un empleado *author Doug Lowe *author LoweWriter.com *version 1.5 *since 1.0 * / public class Empleado {private String lastName-privada salario doble cadena firstName-privada. - / ** Representa la dirección del empleado * / dirección Dirección público -.. / ** Crea un empleado con el nombre especificado *param apellido apellido del empleado *param firstName nombre del empleado * / Empleado público (String.. lastName, Cadena firstName) {this.lastName = lastName-this.firstName = firstName-this.address = new Direccion () -} / ** Obtiene el apellido del empleado *return Una cadena que representa el pasado * el nombre del empleado. *. / public String getLastName () {return this.lastName -} / ** Establece el apellido del empleado *param apellido String que contiene * Apellido del empleado * / public void setLastName (String lastName) {this.lastName = lastName.. -..} / ** Obtiene primero el nombre del empleado *return Una cadena que representa primero * Nombre * / public String getFirstName del empleado () {return this.firstName -} / ** Establece primero el nombre del empleado *param firstName. Una cadena que contiene el * nombre del empleado * / public void setFirstName (String firstName) {this.firstName = firstName -}... / ** Obtiene el salario del empleado *return Un doble que representa el salario del empleado * / double getSalary pública ( ) {return this.salary -} / ** Establece el salario del empleado *param lastName Un doble que contiene * salario del empleado * / public void setSalary (doble sueldo) {this.salary = SALARIO}}..

Usando el comando javadoc

los javadoc comando tiene unas cuantas docenas de opciones que puede establecer, por lo que es un comando complicado de usar. Sin embargo, puede pasar por alto todas estas opciones para crear un conjunto básico de páginas de documentación. Sólo especifique la ruta de acceso completa a todos los archivos de Java que desea crear documentación para, de esta manera:

javadoc com lowewriter nómina *. 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 dom

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, sólo tienes que escribir index.html en el símbolo del sistema después de ejecutar el comando javadoc. O usted puede comenzar su navegador, vaya al directorio donde ha creado las páginas de documentación, y abra la página index.html.

imagen0.jpg

Si crees que esta página me resulta familiar, es porque la documentación de la API de Java se ha creado usando JavaDocs. Así que usted ya debe saber cómo encontrar su camino alrededor de estas páginas.

Para ver 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 desde el archivo de origen.

image1.jpg


» » » » Cómo usar javadoc para documentar sus clases