JavaDoc: ¿dónde agregar notas / comentarios a la documentación?

Al codificar en C# siempre he encontrado la etiqueta remarks muy útil para proporcionar notas sobre la implementación de una clase o método, o para dar información sobre la teoría de lo que estaba implementando. Ahora estoy usando Java, pero no puedo encontrar una etiqueta JavaDoc apropiada para esto. Tal vez en Java logras esto de una manera diferente, ¿alguien lo sabe?

Author: Jonathan Leffler, 2011-04-11
Source

4 answers

Por lo que sé, no hay ninguna etiqueta Javadoc dedicada para notas o comentarios. Generalmente, la primera frase de Javadoc debe dar una breve descripción de la clase / método / campo. A continuación, la descripción completa debe seguir. Y si desea incluir alguna nota, un párrafo especializado con una "Nota:" precedida debería ser suficiente.

/**
 * Brief description. Full description of the method, generally without
 * implementation details.
 * <p>
 * Note: Additional information, e.g. your implementation notes or remarks.
 * </p>
 * @param input description of the parameter
 * @return description of return value
 * 
 * @since version
 * @author name of the author
 */
public boolean doSomething(String input)
{
    // your code
}
 42
Author: janhink,
Warning: date(): Invalid date.timezone value 'Europe/Kyiv', we selected the timezone 'UTC' for now. in /var/www/agent_stack/data/www/ajaxhispano.com/template/agent.layouts/content.php on line 61
2013-06-26 07:36:04

Con la iteración 8 del lenguaje de programación Java, los desarrolladores finalmente han recibido tres etiquetas adicionales que pueden usar en la documentación de su código, y que deberían satisfacer sus necesidades: @apiNote, @implSpec y @implNote (cf. por ejemplo, para una discusión más detallada: blog.codefx.org/java/new-javadoc-tags/).

 14
Author: fbahr,
Warning: date(): Invalid date.timezone value 'Europe/Kyiv', we selected the timezone 'UTC' for now. in /var/www/agent_stack/data/www/ajaxhispano.com/template/agent.layouts/content.php on line 61
2015-12-22 21:46:20

Si crees que los detalles de implementación son lo suficientemente interesantes como para formar parte de Javadoc, simplemente debes proporcionarlos en un párrafo en el comentario de Javadoc: 

/**
 * Does something.
 * <p>
 * <b>Implementation details:</b><br />
 * Blah blah blah...
 * </p>
 */
public void doSomething() {
    // ...
}
 5
Author: Laurent Pireyn,
Warning: date(): Invalid date.timezone value 'Europe/Kyiv', we selected the timezone 'UTC' for now. in /var/www/agent_stack/data/www/ajaxhispano.com/template/agent.layouts/content.php on line 61
2011-04-11 09:57:59

También puedes crear tus propias etiquetas personalizadas.

Aquí hay un comentario de javadoc que incluye la etiqueta personalizada "@ note": 

    /**
     * Quark represents a quark.
     *
     * @note If you spin a quark, it will spin forever!
     */
    public class Quark {

    }

Para generar javadocs para lo anterior, ejecute javadoc de la siguiente manera:

Javadoc-tag nota:a:"Nota:" Quark.java

Fuente: http://www.developer.com/java/other/article.php/3085991/Javadoc-Programming.htm

 4
Author: Naveen,
Warning: date(): Invalid date.timezone value 'Europe/Kyiv', we selected the timezone 'UTC' for now. in /var/www/agent_stack/data/www/ajaxhispano.com/template/agent.layouts/content.php on line 61
2015-08-25 21:53:42