Java Language => Documentando 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.

Documentación de la clase

Todos los comentarios de Javadoc comienzan con un comentario de bloqueo seguido de un asterisco ( /** ) y finalizan cuando el comentario de bloqueo ( */ ). Opcionalmente, cada línea puede comenzar con espacios en blanco arbitrarios y un solo asterisco; estos se ignoran cuando se generan los archivos de documentación.

/**
 * Brief summary of this class, ending with a period.
 *
 * It is common to leave a blank line between the summary and further details.
 * The summary (everything before the first period) is used in the class or package 
 * overview section.
 *
 * The following inline tags can be used (not an exhaustive list): 
 * {@link some.other.class.Documentation} for linking to other docs or symbols
 * {@link some.other.class.Documentation Some Display Name} the link's appearance can be 
 * customized by adding a display name after the doc or symbol locator
 * {@code code goes here} for formatting as code
 * {@literal <>[]()foo} for interpreting literal text without converting to HTML markup 
 * or other tags.
 *
 * Optionally, the following tags may be used at the end of class documentation 
 * (not an exhaustive list):
 *
 * @author John Doe
 * @version 1.0
 * @since 5/10/15
 * @see some.other.class.Documentation
 * @deprecated This class has been replaced by some.other.package.BetterFileReader
 * 
 * You can also have custom tags for displaying additional information.
 * Using the @custom.<NAME> tag and the -tag custom.<NAME>:htmltag:"context"
 * command line option, you can create a custom tag.
 *
 * Example custom tag and generation:
 * @custom.updated 2.0    
 * Javadoc flag: -tag custom.updated:a:"Updated in version:"
 * The above flag will display the value of @custom.updated under "Updated in version:"
 *
 */
public class FileReader {
}

Las mismas etiquetas y formato que se usan para las Classes se pueden usar para Enums e Interfaces .

Método de Documentación

/**
 * Brief summary of method, ending with a period.
 *
 * Further description of method and what it does, including as much detail as is 
 * appropriate.  Inline tags such as
 * {@code code here}, {@link some.other.Docs}, and {@literal text here} can be used.
 *
 * If a method overrides a superclass method, {@inheritDoc} can be used to copy the 
 * documentation
 * from the superclass method
 *
 * @param stream Describe this parameter.  Include as much detail as is appropriate
 *               Parameter docs are commonly aligned as here, but this is optional.
 *               As with other docs, the documentation before the first period is 
 *               used as a summary.
 *
 * @return Describe the return values.  Include as much detail as is appropriate
 *         Return type docs are commonly aligned as here, but this is optional.
 *         As with other docs, the documentation before the first period is used as a 
 *         summary.
 *
 * @throws IOException Describe when and why this exception can be thrown.
 *                     Exception docs are commonly aligned as here, but this is 
 *                     optional.
 *                     As with other docs, the documentation before the first period 
 *                     is used as a summary.
 *                     Instead of @throws, @exception can also be used.
 *
 * @since 2.1.0
 * @see some.other.class.Documentation
 * @deprecated  Describe why this method is outdated. A replacement can also be specified.
 */
public String[] read(InputStream stream) throws IOException {
    return null;
}

Documentacion de campo

/**
 * Fields can be documented as well.
 * 
 * As with other javadocs, the documentation before the first period is used as a
 * summary, and is usually separated from the rest of the documentation by a blank 
 * line.
 * 
 * Documentation for fields can use inline tags, such as:
 * {@code code here}
 * {@literal text here}
 * {@link other.docs.Here}
 * 
 * Field documentation can also make use of the following tags:
 * 
 * @since 2.1.0
 * @see some.other.class.Documentation
 * @deprecated Describe why this field is outdated
 */
public static final String CONSTANT_STRING = "foo";

Documentación del paquete

Java SE 5

Es posible crear documentación a nivel de paquete en Javadocs usando un archivo llamado package-info.java . Este archivo se debe formatear como se muestra a continuación. Los espacios en blanco iniciales y los asteriscos son opcionales, normalmente están presentes en cada línea por razones de formato

/**
 * Package documentation goes here; any documentation before the first period will 
 * be used as a summary.
 *
 * It is common practice to leave a blank line between the summary and the rest
 * of the documentation; use this space to describe the package in as much detail
 * as is appropriate.
 * 
 * Inline tags such as {@code code here}, {@link reference.to.other.Documentation},
 * and {@literal text here} can be used in this documentation.
 */
package com.example.foo;

// The rest of the file must be empty.

En el caso anterior, debe colocar este archivo package-info.java dentro de la carpeta del paquete de Java com.example.foo .

Campo de golf

El enlace a otros Javadocs se realiza con la etiqueta @link :

/**
 * You can link to the javadoc of an already imported class using {@link ClassName}.
 *
 * You can also use the fully-qualified name, if the class is not already imported: 
 *  {@link some.other.ClassName}
 *
 * You can link to members (fields or methods) of a class like so:
 *  {@link ClassName#someMethod()}
 *  {@link ClassName#someMethodWithParameters(int, String)}
 *  {@link ClassName#someField}
 *  {@link #someMethodInThisClass()} - used to link to members in the current class
 *  
 * You can add a label to a linked javadoc like so:
 *  {@link ClassName#someMethod() link text} 
 */

Con la etiqueta @see puede agregar elementos a la sección Vea también . Como @param o @return el lugar donde aparecen no es relevante. La especificación dice que debes escribirlo después de @return .

/**
 * This method has a nice explanation but you might found further
 * information at the bottom.
 *
 * @see ClassName#someMethod()
 */

Si desea agregar enlaces a recursos externos, solo puede usar la etiqueta HTML <a> . Puede usarlo en línea en cualquier lugar o dentro de las etiquetas @link y @see .

/**
 * Wondering how this works? You might want
 * to check this <a href="http://stackoverflow.com/">great service</a>.
 *
 * @see <a href="http://stackoverflow.com/">Stack Overflow</a>
 */

Construyendo Javadocs desde la línea de comando

Muchos IDE proporcionan soporte para generar HTML desde Javadocs automáticamente; Algunas herramientas de compilación ( Maven y Gradle , por ejemplo) también tienen complementos que pueden manejar la creación de HTML.

Sin embargo, estas herramientas no son necesarias para generar el HTML Javadoc; Esto se puede hacer utilizando la herramienta de línea de comandos javadoc .

El uso más básico de la herramienta es:

javadoc JavaFile.java

Lo que generará HTML a partir de los comentarios de Javadoc en JavaFile.java .

Un uso más práctico de la herramienta de línea de comandos, que leerá recursivamente todos los archivos java en [source-directory] , creará la documentación para [package.name] y todos los subpaquetes, y colocará el HTML generado en el [docs-directory] es:

javadoc -d [docs-directory] -subpackages -sourcepath [source-directory] [package.name]

Documentación del código en línea

Aparte del código de documentación Javadoc se puede documentar en línea.

Los comentarios de una sola línea se inician con // y se pueden colocar después de una declaración en la misma línea, pero no antes.

public void method() {
  
  //single line comment
  someMethodCall(); //single line comment after statement
  
}

Los comentarios multilínea se definen entre /* y */ . Pueden abarcar varias líneas e incluso pueden colocarse entre sentencias.

public void method(Object object) {
  
  /*
    multi 
    line 
    comment
  */
  object/*inner-line-comment*/.method(); 
}

Los JavaDocs son una forma especial de comentarios de varias líneas, comenzando con /** .

Como demasiados comentarios en línea pueden disminuir la legibilidad del código, se deben usar de forma dispersa en caso de que el código no se explique lo suficiente o la decisión de diseño no sea obvia.

Un caso de uso adicional para los comentarios de una sola línea es el uso de TAG, que son palabras clave cortas y basadas en convenciones. Algunos entornos de desarrollo reconocen ciertas convenciones para dichos comentarios individuales. Ejemplos comunes son

//TODO
//FIXME

O emitir referencias, es decir, para Jira.

//PRJ-1234

Fragmentos de código dentro de la documentación.

La forma canónica de escribir código dentro de la documentación es con la construcción {@code } . Si tiene código multilínea dentro de <pre></pre> .

/**
 * The Class TestUtils.
 * <p>
 * This is an {@code inline("code example")}.
 * <p>
 * You should wrap it in pre tags when writing multiline code.
 * <pre>{@code
 *  Example example1 = new FirstLineExample();
 *  example1.butYouCanHaveMoreThanOneLine();
 * }</pre>
 * <p>
 * Thanks for reading.
 */
class TestUtils {

A veces es posible que necesite poner un código complejo dentro del comentario javadoc. El signo @ es especialmente problemático. El uso de la etiqueta <code> antigua junto con la construcción {@literal } resuelve el problema.

/**
 * Usage:
 * <pre><code>
 * class SomethingTest {
 * {@literal @}Rule
 *  public SingleTestRule singleTestRule = new SingleTestRule("test1");
 *
 * {@literal @}Test
 *  public void test1() {
 *      // only this test will be executed
 *  }
 *
 *  ...
 * }
 * </code></pre>
 */
class SingleTestRule implements TestRule { }

Modified text is an extract of the original Stack Overflow Documentation

Licenciado bajo CC BY-SA 3.0

No afiliado a Stack Overflow

Java Language
Documentando el código de Java

Buscar..