Java LanguageDocumentando el código de Java


Introducción

La documentación para el código java a menudo se genera utilizando javadoc . Javadoc fue creado por Sun Microsystems con el propósito de generar documentación de API en formato HTML desde el código fuente de Java. El uso del formato HTML brinda la comodidad de poder vincular documentos relacionados entre sí.

Sintaxis

  • / ** - inicio de JavaDoc en una clase, campo, método o paquete
  • @author // Para nombrar al autor de la clase, interfaz o enumeración. Es requerido.
  • @version // La versión de esa clase, interfaz o enumeración. Es requerido. Puede usar macros como% I% o% G% para que el software de control de origen complete en el proceso de pago.
  • @param // Para mostrar los argumentos (parámetros) de un método o un constructor. Especifique una etiqueta @param para cada parámetro.
  • @return // Para mostrar los tipos de retorno para métodos no nulos.
  • @exception // Muestra qué excepciones se pueden lanzar desde el método o el constructor. Las excepciones que DEBEN ser capturadas deben enumerarse aquí. Si lo desea, también puede incluir aquellos que no necesitan ser capturados, como ArrayIndexOutOfBoundsException. Especifique una @excepción para cada excepción que se pueda lanzar.
  • @throws // Igual que @exception.
  • @see // Enlaces a un método, campo, clase o paquete. Utilizar en la forma de package.Class # algo.
  • @since // Cuando este método, campo o clase fue agregado. Por ejemplo, JDK-8 para una clase como java.util.Optional <T> .
  • @serial, @serialField, @serialData // Se usa para mostrar el serialVersionUID.
  • @deprecated // Para marcar una clase, método o campo como obsoleto. Por ejemplo, uno sería java.io.StringBufferInputStream . Vea una lista completa de las clases en desuso existentes aquí .
  • {@link} // Similar a @see, pero se puede usar con texto personalizado: {@link #setDefaultCloseOperation (int closeOperation) vea JFrame # setDefaultCloseOperation para más información}.
  • {@linkplain} // Similar a {@link}, pero sin la fuente del código.
  • {@code} // Para código literal, como etiquetas HTML. Por ejemplo: {@code <html> </html>}. Sin embargo, esto usará una fuente monoespaciada. Para obtener el mismo resultado sin la fuente monoespaciado, use {@literal}.
  • {@literal} // Igual que {@code}, pero sin la fuente monoespaciada.
  • {@value} // Muestra el valor de un campo estático: El valor de JFrame # EXIT_ON_CLOSE es {@value}. O, podría vincular a un campo determinado: utiliza el nombre de la aplicación {@value AppConstants # APP_NAME}.
  • {@docRoot} // La carpeta raíz del HTML de JavaDoc relativa al archivo actual. Ejemplo: <a href="{@docRoot}/credits.html"> Créditos </a>.
  • Se permite HTML: <code> "Hola cookies" .substring (3) </code>.
  • * / - final de la declaración de JavaDoc

Observaciones

Javadoc es una herramienta incluida con el JDK que permite que los comentarios en código se conviertan a una documentación HTML. La especificación de la API de Java se generó utilizando Javadoc. Lo mismo es cierto para gran parte de la documentación de las bibliotecas de terceros.

Documentando el código de Java Ejemplos relacionados