Respuestas:
La primera forma se llama Javadoc . Usas esto cuando escribes API formales para tu código, que son generadas por la javadocherramienta. Por ejemplo, la página API de Java 7 usa Javadoc y fue generada por esa herramienta.
Algunos elementos comunes que verías en Javadoc incluyen:
@param: esto se utiliza para indicar qué parámetros se pasan a un método y qué valor se espera que tengan
@return: esto se utiliza para indicar qué resultado devolverá el método
@throws: esto se utiliza para indicar que un método arroja una excepción o error en caso de cierta entrada
@since: esto se utiliza para indicar la primera versión de Java en la que esta clase o función estaba disponible
Como ejemplo, aquí está Javadoc para el comparemétodo de Integer:
/**
* Compares two {@code int} values numerically.
* The value returned is identical to what would be returned by:
* <pre>
* Integer.valueOf(x).compareTo(Integer.valueOf(y))
* </pre>
*
* @param x the first {@code int} to compare
* @param y the second {@code int} to compare
* @return the value {@code 0} if {@code x == y};
* a value less than {@code 0} if {@code x < y}; and
* a value greater than {@code 0} if {@code x > y}
* @since 1.7
*/
public static int compare(int x, int y) {
return (x < y) ? -1 : ((x == y) ? 0 : 1);
}
La segunda forma es un comentario de bloque (multilínea). Utiliza esto si quieres tener múltiples líneas en un comentario.
Diré que solo querrás usar la última forma con moderación ; es decir, no desea sobrecargar su código con comentarios de bloque que no describen qué comportamientos se supone que tiene el método / función compleja.
Dado que Javadoc es el más descriptivo de los dos, y puede generar documentación real como resultado de su uso, sería más preferible usar Javadoc que los simples comentarios de bloque.
Para el lenguaje de programación Java , no hay diferencia entre los dos. Java tiene dos tipos de comentarios: comentarios tradicionales ( /* ... */) y comentarios de fin de línea ( // ...). Consulte la Especificación del lenguaje Java . Por lo tanto, para el lenguaje de programación Java, tanto /* ... */y /** ... */son ejemplos de los comentarios tradicionales, y ambos están tratados exactamente de la misma por el compilador de Java, es decir, que son ignorados (o más correctamente: en que son tratados como espacios en blanco).
Sin embargo, como programador de Java, no solo utiliza un compilador de Java. Utiliza una cadena de herramientas completa, que incluye, por ejemplo, el compilador, un IDE, un sistema de compilación, etc. Y algunas de estas herramientas interpretan las cosas de manera diferente que el compilador de Java. En particular, los /** ... */comentarios son interpretados por la herramienta Javadoc, que se incluye en la plataforma Java y genera documentación. La herramienta Javadoc escaneará el archivo fuente Java e interpretará las partes intermedias /** ... */como documentación.
Esto es similar a las etiquetas como FIXMEy TODO: si incluye un comentario como // TODO: fix thiso // FIXME: do that, la mayoría de los IDE resaltarán dichos comentarios para que no se olvide de ellos. Pero para Java, son solo comentarios.
javadocherramienta no puede interpretar algo.
Al leer la sección 3.7 de JLS, explique todo lo que necesita saber sobre los comentarios en Java.
Hay dos tipos de comentarios:
- / * texto * /
Un comentario tradicional: todo el texto de los caracteres ASCII / * a los caracteres ASCII * / se ignora (como en C y C ++).
- //texto
Un comentario de fin de línea: se ignora todo el texto desde los caracteres ASCII // hasta el final de la línea (como en C ++).
Acerca de su pregunta,
El primero
/**
*
*/
se utiliza para declarar la tecnología Javadoc .
Javadoc es una herramienta que analiza las declaraciones y los comentarios de documentación en un conjunto de archivos de origen y produce un conjunto de páginas HTML que describen las clases, interfaces, constructores, métodos y campos. Puede usar un dodoct Javadoc para personalizar la salida de Javadoc. Un doclet es un programa escrito con la API de Doclet que especifica el contenido y el formato de la salida que generará la herramienta. Puede escribir un doclet para generar cualquier tipo de salida de archivo de texto, como HTML, SGML, XML, RTF y MIF. Oracle proporciona un doclet estándar para generar documentación de API en formato HTML. Los Doclets también se pueden usar para realizar tareas especiales no relacionadas con la producción de documentación API.
Para obtener más información, Docletconsulte la API .
El segundo, como se explica claramente en JLS, ignorará todo el texto entre ellos /*y, por lo */tanto, se usará para crear comentarios multilínea.
Algunas otras cosas que quizás quieras saber sobre los comentarios en Java
/* and */no tienen un significado especial en los comentarios que comienzan con //.//no tiene un significado especial en los comentarios que comienzan con /* or /**.Por lo tanto, el siguiente texto es un solo comentario completo:
/* this comment /* // /** ends here: */No creo que las respuestas existentes hayan abordado adecuadamente esta parte de la pregunta:
¿Cuándo debo usarlos?
Si está escribiendo una API que se publicará o reutilizará dentro de su organización, debe escribir comentarios exhaustivos de Javadoc para cada publicclase, método y campo, así como protectedmétodos y campos de no finalclases. Javadoc debe cubrir todo lo que no puede ser transmitido por la firma del método, como condiciones previas, condiciones posteriores, argumentos válidos, excepciones de tiempo de ejecución, llamadas internas, etc.
Si está escribiendo una API interna (una que es utilizada por diferentes partes del mismo programa), Javadoc es posiblemente menos importante. Pero para beneficio de los programadores de mantenimiento, aún debe escribir Javadoc para cualquier método o campo donde el uso o significado correcto no sea obvio de inmediato.
La "característica asesina" de Javadoc es que está estrechamente integrada con Eclipse y otros IDE. Un desarrollador solo necesita pasar el puntero del mouse sobre un identificador para aprender todo lo que necesita saber al respecto. Hacer referencia constante a la documentación se convierte en una segunda naturaleza para los desarrolladores experimentados de Java, lo que mejora la calidad de su propio código. Si su API no está documentada con Javadoc, los desarrolladores experimentados no querrán usarla.
Los comentarios en la siguiente lista de Java Code son caracteres en gris:
/**
* The HelloWorldApp class implements an application that
* simply displays "Hello World!" to the standard output.
*/
class HelloWorldApp {
public static void main(String[] args) {
System.out.println("Hello World!"); //Display the string.
}
}El lenguaje Java admite tres tipos de comentarios:
/* text */El compilador ignora todo, desde /*hasta */.
/** documentation */Esto indica un comentario de documentación (comentario de documento, para abreviar). El compilador ignora este tipo de comentario, al igual que ignora los comentarios que usan /*y */. La herramienta JDK javadoc utiliza comentarios de documentos al preparar documentación generada automáticamente.
// textEl compilador ignora todo desde //el final de la línea.
Ahora con respecto a cuándo debería usarlos:
Úselo // textcuando desee comentar una sola línea de código.
Úselo /* text */cuando desee comentar varias líneas de código.
Úselo /** documentation */ cuando desee agregar información sobre el programa que se puede utilizar para la generación automática de documentación del programa.
El primero es para Javadoc que usted define en la parte superior de las clases, interfaces, métodos, etc. Puede usar Javadoc como su nombre sugiere documentar su código sobre lo que hace la clase o qué método hace, etc. y generar un informe al respecto.
El segundo es el comentario de bloque de código. Digamos, por ejemplo, que tiene algún bloque de código que no desea que el compilador interprete y luego utilice el comentario de bloque de código.
otro es // esto lo usa a nivel de enunciado para especificar lo que se supone que deben hacer las líneas de códigos anteriores.
Hay otros también como // TODO, esto marcará que quieres hacer algo más tarde en ese lugar
// FIXME puede usar cuando tiene alguna solución temporal pero desea visitarla más tarde y mejorarla.
Espero que esto ayude
Java admite dos tipos de comentarios:
/* multiline comment */: El compilador ignora todo, desde /*hasta */. El comentario puede abarcar varias líneas.
// single line: El compilador ignora todo desde //el final de la línea.
Algunas herramientas como javadoc usan un comentario especial de varias líneas para su propósito. Por ejemplo, /** doc comment */es un comentario de documentación utilizado por javadoc al preparar la documentación generada automáticamente, pero para Java es un simple comentario multilínea.
/** .. */es solo un comentario multilínea regular, y el primer carácter que contiene es un asterisco.