in

Cómo escribir comentarios de documentos para la herramienta Javadoc

Página de inicio de Javadoc

Este documento describe la guía de estilo, las convenciones de etiquetas e imágenes que usamos en los comentarios de la documentación para los programas Java escritos en Java Software, Oracle. No repite el material relacionado cubierto en otra parte:

Contenido

  • Introducción
  • Escribir comentarios de documentos

Introducción

Principios

En Java Software, tenemos varias pautas que pueden hacer que los comentarios de nuestra documentación sean diferentes a los de los desarrolladores externos. Nuestros comentarios de documentación definen el oficial Especificación de la API de la plataforma Java. Con este fin, nuestro público objetivo son aquellos que escriben pruebas de compatibilidad con Java, o conforman o vuelven a implementar la plataforma Java, además de los desarrolladores. Dedicamos tiempo y esfuerzo a especificar condiciones de límite, rangos de argumentos y casos de esquina en lugar de definir términos de programación comunes, redactar descripciones conceptuales e incluir ejemplos para desarrolladores.

Por lo tanto, comúnmente hay dos formas diferentes de escribir comentarios de documentos: como especificaciones de API o como documentación de guía de programación. Estos dos objetivos se describen en las siguientes secciones. Un personal con recursos generosos puede permitirse combinar ambos en la misma documentación (correctamente «fragmentada»); sin embargo, nuestras prioridades dictan que nos concentremos principalmente en escribir especificaciones de API en los comentarios de documentos. Esta es la razón por la que los desarrolladores a menudo necesitan recurrir a otros documentos, como Documentación técnica de Java SE y Los tutoriales de Java para guías de programación.

Escribir especificaciones de API

Idealmente, la especificación de la API de Java comprende todas las afirmaciones necesarias para realizar una implementación de sala limpia de la plataforma Java para «escribir una vez, ejecutar en cualquier lugar», de modo que cualquier subprograma o aplicación Java se ejecutará de la misma manera en cualquier implementación. Esto puede incluir afirmaciones en los comentarios del documento más las de cualquier especificación arquitectónica y funcional (generalmente escrita en FrameMaker) o en cualquier otro documento. Esta definición es un objetivo elevado y existe una limitación práctica en cuanto a qué tan completamente podemos especificar la API. Los siguientes son principios rectores que intentamos seguir:

Redacción de la documentación de la guía de programación

Lo que separa las especificaciones de API de una guía de programación son ejemplos, definiciones de términos de programación comunes, ciertas descripciones conceptuales (como metáforas) y descripciones de errores de implementación y soluciones. No hay duda de que estos contribuyen a la comprensión del desarrollador y ayudan a un desarrollador a escribir aplicaciones confiables más rápidamente. Sin embargo, debido a que estos no contienen «aserciones» de API, no son necesarios en una especificación de API. Puede incluir parte o toda esta información en los comentarios de la documentación (y puede incluir etiquetas personalizadas, manejado por un doclet personalizado, para facilitarlo). En Java Software, conscientemente no incluimos este nivel de documentación en los comentarios del documento, y en su lugar incluimos enlaces a esta información (enlaces al Tutorial de Java y la lista de cambios) o incluimos esta información en el mismo paquete de descarga de documentación que la especificación de la API. – el paquete de documentación de JDK incluye las especificaciones de la API, así como demostraciones, ejemplos y guías de programación.

Es útil entrar en más detalles sobre cómo documentar errores y soluciones. A veces hay una discrepancia entre la forma en que el código deberían funciona y cómo funciona realmente. Esto puede tomar dos formas diferentes: errores de especificación de API y errores de código. Es útil decidir de antemano si desea documentarlos en los comentarios del documento. En Java Software hemos decidido documentar ambos fuera de los comentarios del documento, aunque hacemos excepciones.

Errores de especificación de API son errores que están presentes en la declaración del método o en el comentario del documento que afectan la sintaxis o la semántica. Un ejemplo de tal error de especificación es un método que se especifica para lanzar una NullPointerException cuando null se pasa, pero null es en realidad un parámetro útil que debería aceptarse (e incluso se implementó de esa manera). Si se toma la decisión de corregir la especificación de la API, sería útil indicarlo en la propia especificación de la API, en una lista de cambios a la especificación o en ambos. Documentar una diferencia de API como esta en un comentario de documento, junto con su solución, alerta al desarrollador sobre el cambio donde es más probable que lo vea. Tenga en cuenta que una especificación de API con esta corrección aún mantendría su independencia de implementación.

Errores de código son errores en la implementación en lugar de en la especificación de la API. Los errores de código y sus soluciones a menudo también se distribuyen por separado en un informe de error. Sin embargo, si la herramienta Javadoc se está utilizando para generar documentación para una implementación en particular, sería muy útil incluir esta información en los comentarios del documento, convenientemente separada como una nota o por una etiqueta personalizada (digamos @bug).

Quién posee y edita los comentarios del documento

Los comentarios del documento para la especificación de la API de la plataforma Java pertenecen a los programadores. Sin embargo, son editados tanto por programadores como por escritores. Es una premisa básica que los escritores y programadores respetan las capacidades de los demás y ambos contribuyen a los mejores comentarios de documentos posibles. A menudo, es una cuestión de negociación determinar quién escribe qué partes de la documentación, según el conocimiento, el tiempo, los recursos, el interés, la complejidad de la API y el estado de la implementación en sí. Pero los comentarios finales deben ser aprobados por el ingeniero responsable.

Idealmente, la persona que diseña la API escribiría la especificación de la API en archivos fuente de esqueleto, con solo declaraciones y comentarios de documentos, completando la implementación solo para cumplir con el contrato de API escrito. El propósito de un escritor de API es aliviar al diseñador de parte de este trabajo. En este caso, el diseñador de API escribiría los comentarios iniciales del documento utilizando un lenguaje disperso y luego el escritor revisaría los comentarios, refinaría el contenido y agregaría etiquetas.

Si los comentarios del documento son una especificación de API para re-implementadores, y no simplemente una guía para desarrolladores, deben ser escritos por el programador que diseñó e implementó la API, o por un escritor de API que sea o se haya convertido en un experto en la materia. . Si la implementación está escrita según las especificaciones pero los comentarios del documento no están terminados, un escritor puede completar los comentarios del documento inspeccionando el código fuente o escribiendo programas que prueben la API. Un escritor puede inspeccionar o probar las excepciones lanzadas, las condiciones de los límites de los parámetros y la aceptación de argumentos nulos. Sin embargo, surge una situación mucho más difícil si la implementación es no escrito según las especificaciones. Entonces, un escritor puede proceder a escribir una especificación de API solo si conoce la intención del diseñador (ya sea a través de reuniones de diseño o mediante una especificación de diseño escrita por separado) o tiene acceso inmediato al diseñador con sus preguntas. Por lo tanto, puede ser más difícil para un escritor escribir la documentación para interfaces y clases abstractas que no tienen implementadores.

Teniendo esto en cuenta, estas pautas están destinadas a describir los comentarios de la documentación final. Están pensados ​​como sugerencias en lugar de requisitos que deben seguirse servilmente si parecen demasiado onerosos o si se pueden encontrar alternativas creativas. Cuando se desarrolla un sistema complejo como Java (que contiene alrededor de 60 paquetes), a menudo un grupo de ingenieros contribuye a un conjunto particular de paquetes, como javax.swing puede desarrollar pautas que sean diferentes a las de otros grupos. Esto puede deberse a los diferentes requisitos de esos paquetes o debido a limitaciones de recursos.

Terminología

Documentación de la API (Documentos API) o Especificaciones API (Especificaciones de API)

Descripciones en línea o en papel de la API, destinadas principalmente a programadores que escriben en Java. Estos pueden generarse utilizando la herramienta Javadoc o crearse de alguna otra manera. Una especificación de API es un tipo particular de documento de API, como se describe encima. Un ejemplo de una especificación de API es el Plataforma Java, Especificación de API Standard Edition 7.

Comentarios de documentación (comentarios del documento)

Los comentarios especiales en el código fuente de Java que están delimitados por el /** ... */ delimitadores. Estos comentarios son procesados ​​por la herramienta Javadoc para generar los documentos API.

javadoc

La herramienta JDK que genera documentación API a partir de comentarios de documentación.

Archivos fuente

La herramienta Javadoc puede generar resultados a partir de cuatro tipos diferentes de archivos «fuente»:

  • Archivos de código fuente para clases de Java (.java): contienen comentarios de clase, interfaz, campo, constructor y método.
  • Archivos de comentarios de paquetes: contienen comentarios de paquetes
  • Archivos de comentarios de descripción general: contienen comentarios sobre el conjunto de paquetes
  • Varios archivos sin procesar: estos incluyen imágenes, código fuente de muestra, archivos de clase, subprogramas, archivos HTML y cualquier otra cosa que desee consultar de los archivos anteriores.

Para obtener más detalles, consulte: Archivos fuente.

Escribir comentarios de documentos

Formato de un comentario de documento

Un comentario de documento está escrito en HTML y debe preceder a una declaración de clase, campo, constructor o método. Se compone de dos partes: una descripción seguida de etiquetas de bloque. En este ejemplo, las etiquetas de bloque son @param, @return, y @see.



/**
* Returns an Image object that can then be painted on the screen. 
* The url argument must specify an absolute {@link URL}. The name
* argument is a specifier that is relative to the url argument. 
* <p>
* This method always returns immediately, whether or not the 
* image exists. When this applet attempts to draw the image on
* the screen, the data will be loaded. The graphics primitives 
* that draw the image will incrementally paint on the screen. 
*
* @param  url  an absolute URL giving the base location of the image
* @param  name the location of the image, relative to the url argument
* @return      the image at the specified URL
* @see         Image
*/
public Image getImage(URL url, String name) {
try {
return getImage(new URL(url, name));
} catch...

Deja una respuesta

Tu dirección de correo electrónico no será publicada. Los campos obligatorios están marcados con *

14qwPPXu817evjjb7Q I9oQ

Java vs JavaScript: ¿Cuál es la mejor opción para 2021? (Actualizado)

Tablas HTML