what is javadoc how use it generate documentation
Este tutorial explica qué son la herramienta JavaDoc y los comentarios y métodos de JavaDoc para generar documentación de código:
JavaDoc es una herramienta especial empaquetada con el JDK. Se utiliza para generar la documentación del código fuente de Java en formato HTML.
Es un generador de documentación para el lenguaje Java de Sun Microsystems (actualmente Oracle Corporation).
descargador de video gratuito desde cualquier sitio versión completa
=> Consulte TODOS los tutoriales de Java aquí.
Lo que vas a aprender:
¿Qué es JavaDoc?
Esta herramienta utiliza el formato de 'comentarios de documentos' para documentar las clases de Java. Los IDE como Eclipse, IntelliJIDEA o NetBeans tienen una herramienta JavaDoc incorporada para generar documentación HTML. También tenemos muchos editores de archivos en el mercado que pueden ayudar al programador a producir fuentes JavaDoc.
Además de la documentación del código fuente, esta herramienta también proporciona API que crea 'doclets' y 'etiquetas' que usamos para analizar la estructura de una aplicación Java.
Un punto a tener en cuenta es que esta herramienta no afecta el rendimiento de la aplicación de ninguna manera ya que el compilador elimina todos los comentarios durante la compilación del programa Java.
Escribir comentarios en el programa y luego usar JavaDoc para generar la documentación es ayudar al programador / usuario a comprender el código.
La documentación HTML generada por JavaDoc es documentación de API. Analiza las declaraciones y genera un conjunto de archivos fuente. El archivo fuente describe campos, métodos, constructores y clases.
Tenga en cuenta que antes de utilizar la herramienta JavaDoc en nuestro código fuente, debemos incluir comentarios especiales de JavaDoc en el programa.
Pasemos ahora a los comentarios.
Comentarios de JavaDoc
El lenguaje Java admite los siguientes tipos de comentarios.
# 1) Comentarios de una sola línea: El comentario de una sola línea se indica con ' // ”Y cuando el compilador los encuentra, ignora todo lo que sigue a estos comentarios hasta el final de la línea.
# 2) Comentarios multilínea: Los comentarios de varias líneas se representan mediante ' /*….*/ ”. Entonces, al encontrar la secuencia '/ *', el compilador ignora todo lo que sigue a esta secuencia hasta que encuentra la secuencia de cierre '* /'.
# 3) Comentarios sobre la documentación: Estos se denominan comentarios de documentos y la herramienta los utiliza para generar documentación API. Los comentarios del documento se indican como ' / ** documentación * / ”. Como podemos ver, estos comentarios son diferentes de los comentarios normales descritos anteriormente. Los comentarios del documento también pueden contener etiquetas HTML dentro de ellos, como veremos en breve.
Entonces, para generar documentación de API usando esta herramienta, debemos proporcionar estos comentarios de documentación (comentarios de documentación) en nuestro programa.
Estructura de un comentario de JavaDoc
La estructura del comentario de documento en Java es similar al comentario de varias líneas excepto que el comentario de documento tiene un asterisco adicional (*) en la etiqueta de apertura. Entonces, el comentario del documento comienza con '/ **' en lugar de '/ *'.
Además, los comentarios de estilo JavaDoc también pueden tener etiquetas HTML dentro.
Formato de comentario JavaDoc
Basándonos en la construcción de programación sobre la que queremos documentar, podemos colocar comentarios de documentos sobre cualquier construcción como clase, método, campo, etc. Veamos ejemplos de cada uno de los comentarios de documentación de las construcciones.
Formato de nivel de clase
El formato de comentario del documento a nivel de clase se verá como se muestra a continuación:
|_+_|Como se muestra arriba, un comentario de documento a nivel de clase tendrá todos los detalles, incluido el autor de la clase, los enlaces, si los hay, etc.
Formato de nivel de método
A continuación se muestra un ejemplo de un formato de documento a nivel de método.
C ++ preguntas y respuestas de la entrevista pdf|_+_|
Como podemos ver en el ejemplo anterior, podemos tener cualquier número de etiquetas en el comentario de documento del método. También podemos tener párrafos dentro de la descripción del comentario indicado por
…
.También tenemos etiquetas especiales para describir el valor de retorno (@return) y los parámetros del método (@param).
Formato de nivel de campo
El siguiente ejemplo muestra el comentario de documento de un campo.
|_+_|Como se ve en el ejemplo anterior, también podemos tener comentarios simples sin etiquetas. Tenga en cuenta que JavaDoc no genera ninguna documentación para campos privados a menos que especifiquemos una opción privada con el comando JavaDoc.
Ahora analicemos las etiquetas que se utilizan con los comentarios del documento.
Etiquetas JavaDoc
Java proporciona varias etiquetas que podemos incluir en el comentario del documento. Cuando usamos estas etiquetas, la herramienta analiza estas etiquetas para generar una API bien formateada a partir del código fuente.
Cada etiqueta distingue entre mayúsculas y minúsculas y comienza con un signo '@'. Cada etiqueta comienza al principio de la línea, como podemos ver en los ejemplos anteriores. De lo contrario, el compilador lo trata como un texto normal. Como convención, las mismas etiquetas se colocan juntas.
Hay dos tipos de etiquetas que podemos usar en el comentario de un documento.
# 1) Bloquear etiquetas : Las etiquetas de bloque tienen la forma de @tag_name .
Las etiquetas de bloque se pueden colocar en la sección de etiquetas y seguir la descripción principal .
# 2) Etiquetas en línea :Las etiquetas en línea se incluyen entre llaves y tienen la forma, {@tag_name} . Las etiquetas en línea se pueden colocar en cualquier lugar dentro del comentario del documento.
La siguiente tabla enumera todas las etiquetas que se pueden usar en los comentarios del documento.
Etiqueta | Descripción | Se aplica a |
---|---|---|
@return descripción | Proporciona una descripción del valor de retorno. | Método |
@autor xyz | Indica el autor de la clase, interfaz o enumeración. | Clase, interfaz, enumeración |
{@docRoot} | Esta etiqueta tiene la ruta relativa al directorio raíz del documento. | Clase, interfaz, enumeración, campo, método |
@version versión | Especifica la entrada de la versión del software. | Clase, interfaz, enumeración |
@ desde que-texto | Especifica desde cuándo existe esta funcionalidad | Clase, interfaz, enumeración, campo, método |
@ver referencia | Especifica referencias (enlaces) a otra documentación | Clase, interfaz, enumeración, campo, método |
@param nombre descripción | Se utiliza para describir el parámetro / argumento del método. | Método |
@exception classname descripción | Especifica la excepción que el método puede arrojar en su código. | Método |
@throws nombre de clase descripción | ||
@descripción obsoleta | Especifica si el método está desactualizado | Clase, interfaz, enumeración, campo, método |
{@inheritDoc} | Se usa para copiar la descripción del método anulado en caso de herencia | Método primordial |
{@link reference} | Proporciona referencias o enlaces a otros símbolos. | Clase, interfaz, enumeración, campo, método |
{@linkplain reference} | Igual que {@link} pero se muestra en texto sin formato. | Clase, interfaz, enumeración, campo, método |
{@value #STATIC_FIELD} | Describe el valor de un campo estático. | Campo estático |
{@code literal} | Se usa para dar formato al texto literal en una fuente de código similar a {@literal}. |_+_| Sabemos que no necesitamos compilar el programa o proyecto para generar JavaDoc. IntelliJIdea Ide proporciona una herramienta incorporada para generar la documentación. Siga los pasos a continuación para generar la documentación usando IntelliJIdea.
Aquí podemos especificar si queremos generar documentación para todo el proyecto o solo para una clase, etc. También podemos especificar el directorio de salida donde se generarán los archivos de documentación. Hay varias otras especificaciones como se muestra en la figura anterior. Haga clic en Aceptar una vez que se hayan especificado todos los parámetros.
Por lo tanto, esta es la forma en que podemos generar documentación utilizando esta herramienta en IntelliJ idea. Podemos seguir pasos similares en otros IDE de Java como Eclipse y / o NetBeans. cómo ordenar una matriz int en java Preguntas frecuentesP # 1) ¿Cuál es el uso de JavaDoc? Responder: La herramienta JavaDoc viene con JDK. Se utiliza para generar la documentación del código para el código fuente de Java en formato HTML. Esta herramienta requiere que los comentarios en el código fuente se proporcionen en un formato predefinido como /**….*/. También se denominan comentarios de documentos. P # 2) ¿Cuál es el ejemplo de documentación de Java? Responder: La herramienta de documentación Java Doc genera archivos HTML para que podamos ver la documentación desde el navegador web. El ejemplo real en vivo de la documentación de JavaDoc es la documentación para las bibliotecas de Java en Oracle Corporation, http://download.oracle.com/javase/6/ docs /fuego/. P # 3) ¿Los métodos privados necesitan JavaDoc? Responder: No. Los campos privados y los métodos son solo para desarrolladores. No es lógico proporcionar documentación para métodos o campos privados que no son accesibles para el usuario final. Java Doc tampoco genera documentación para entidades privadas. P # 4) ¿Qué es el comando JavaDoc? Responder: Este comando analiza las declaraciones y los comentarios de documentos en los archivos fuente de Java y genera las páginas de documentación HTML correspondientes que contienen documentación para clases públicas y protegidas, clases anidadas, constructores, métodos, campos e interfaces. Sin embargo, JavaDoc no genera documentación para entidades privadas y clases internas anónimas. ConclusiónEste tutorial describe la herramienta JavaDoc empaquetada con JDK que es útil para generar la documentación del código para el código fuente de Java en formato HTML. Podemos generar documentación ejecutando el comando Java Doc mediante la herramienta de comando o utilizando la funcionalidad JavaDoc incorporada disponible en la mayoría de los IDE de Java. Vimos cómo podemos usar la herramienta con IntelliJIdea Java IDE para generar documentación. El tutorial también explicó varias etiquetas que se pueden usar con comentarios de documentos para que la herramienta pueda generar documentación fácil de usar detallando toda la información relacionada con el código fuente. => Visite aquí para aprender Java desde cero. Lectura recomendada
^
|