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

Question

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?

Answer 1

Por lo que yo sé, no hay ISN' t cualquier etiqueta de Javadoc dedicada para notas o comentarios. En general, la primera oración de Javadoc debe dar una breve descripción de la clase/método/campo. Entonces la descripción completa debería seguir. Y si desea incluir cualquier nota, un párrafo especializado con una "Nota:" antepuesto 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 
} 

Answer 2

Si cree que los detalles de implementación son lo suficientemente interesante para ser una parte del Javadoc, que simplemente les debe proporcionar en un párrafo en el propio comentario Javadoc:

/** 
* Does something. 
* <p> 
* <b>Implementation details:</b><br /> 
* Blah blah blah... 
* </p> 
*/ 
public void doSomething() { 
    // ... 
} 

Answer 3

Puede crear sus propias etiquetas personalizadas también.

Aquí es un comentario Javadoc que incluye la etiqueta "@note" costumbre:

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

    } 

Para generar javadocs de lo anterior, javadoc funcionar de esta manera:

javadoc nota -tag: una : "Nota:" Quark.java

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

Answer 4

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 deben satisfacer sus necesidades: @apiNote, @implSpec y @implNote (consulte, por ejemplo, para obtener más información discusión: blog.codefx.org/java/new-javadoc-tags/).