¿Hay alguna razón para incluir ambos @version and @since como parte de una clase?javadoc: @version y @since
Parecen ser mutuamente excluyentes.
Además, ¿qué significa %I% and %G% y cómo configurarlos/usarlos?
@version %I%, %G%
gracias
La etiqueta @version debe ser la versión actual de la versión o archivo en cuestión. La sintaxis %I%, %G% son macros que el software de control de origen reemplazaría con la versión actual del archivo y la fecha en que el archivo está desprotegido.
La etiqueta @since se debe utilizar para definir qué versión ha agregado el método, la clase, etc. Esta es su sugerencia para otros desarrolladores que solo deben esperar el método cuando se ejecutan contra una versión particular del paquete. Consideraría estas partes súper importantes de la documentación si está enviando su código como una biblioteca destinada a otra persona.
no veo la forma en que son mutuamente excluyentes. Uno se usa para definir la versión, y el otro se usa para describir, ya que cuando el método está allí. Por ejemplo:
/**
* Does Whatever
* @version 1.2.3
* @since 1.2.0
*
*/
public void myMethod() {
// .......
}
En cuanto a los caracteres que usted ha mencionado, parece patentada, y en cualquier caso no tengo idea de lo que significan.
En primer lugar, @since indica la versión # y NO la fecha, ya que desde qué versión está disponible. Por favor, corrige si me equivoco aquí. Gracias –
Siempre he usado @since para denotar la fecha cuando estoy trabajando en el código no API – tddmonkey
Gracias e interesante, pero Java dice diferente. ¿Es lo que sugiere una práctica común contra la doctrina de Java? –
@version habrá registran cada edición. [1.3.21]
@since es decir desde la versión de lanzamiento será compatible con esta interfaz o etc. [1.3] Yuval Adam es interesante, pero esto no es la norma , el propósito de java doc es que todos puedan entender.
Explicado bien en un artículo de Oracle, How to Write Doc Comments for the Javadoc Tool.
@version... clases e interfaces solamente.
En Java Software, utilizamos @version para la versión SCCS. Consulte "man sccs-get" para más detalles. El consenso parece ser la siguiente:
% I% se incrementa cada vez que se edita y delget un archivo
% G% es la fecha dd/mm/aa
Cuando se crea un archivo, % I% se establece en 1.1. Cuando editas y lo delgas, se incrementa a 1.2.
Algunos desarrolladores omiten la fecha% G% (y lo han estado haciendo) si les resulta demasiado confuso; por ejemplo, 3/4/96, que% G% produciría para el 4 de marzo, sería interpretado por los que están fuera de los Estados Unidos significan el 3 de abril. Algunos desarrolladores incluyen el% U% de tiempo solo si quieren una resolución más fina (debido a múltiples registros en un día).El formato de fecha numérico más claro sería tener la fecha formateada con el año primero, algo como aaaa-mm-dd, como se propone en ISO 8601 y en otros lugares (como http://www.cl.cam.ac.uk/~mgk25/iso-time.html), pero esa mejora debería provenir de SCCS.
@sinceEspecificar la versión del producto cuando el nombre de Java ha sido añadido a la especificación API (si es diferente de la aplicación). Por ejemplo, si se añadió un paquete, clase, interfaz o miembro para la plataforma Java 2, Standard Edition, Especificación API en la versión 1.2, utilice:
/**
* @since 1.2
*/
El estándar Javadoc doclet muestra una "Desde "subtítulo con el argumento de cadena como su texto. Este subtítulo aparece en el texto generado solo en el lugar correspondiente a donde aparece la etiqueta @since en los comentarios del documento fuente (La herramienta Javadoc no lo prolifera en la jerarquía).
(La convención fue una vez "JDK 1.2 @since", sino porque se trata de una especificación de la plataforma Java, no son específicas de la JDK de Oracle o SDK, que han caído "JDK".)
Cuando una se introduce el paquete, especifique una etiqueta @since en la descripción del paquete y cada una de sus clases. (No es necesario agregar etiquetas @since a cada clase, pero es nuestra convención, ya que permite una mayor visibilidad en el código fuente.) En ausencia de etiquetas anuladas, el valor de la etiqueta @since se aplica a cada una de las clases del paquete y miembros.
Cuando se introduce una clase (o interfaz), especifique una etiqueta @since en su descripción de clase y no etiquetas @since en los miembros. Agregue una etiqueta @since solo a los miembros agregados en una versión posterior a la clase. Esto minimiza la cantidad de etiquetas @since.
Si un miembro cambia de protegido a público en una versión posterior, la etiqueta @since no cambiaría, aunque ahora puede ser utilizada por cualquier persona que llama, no solo por subclasistas.
Gracias por la explicación. Si la versión es la versión actual, todas las clases consistirán en #. ¿No es @version? es redundante en ese caso, ya que el cliente y el desarrollador saben qué versión está usando. No veo @version en la API real de Java. Thx –
Sasha: Creo que @version está oculta por defecto, como @author. –
Simplemente no veo el sentido de incluirlo, ya que un desarrollador, naturalmente, debería saber qué versión sacó de los cvs y la utilizó, especialmente si la etiqueta se comparte entre todas las clases del proyecto. –