Anotación para deshabilitar JavaDocs

Question

¿Existe alguna anotación que indique que un determinado método no se incluirá en los JavaDocs aunque sea público?

Algo así como:

@nojavadocs 
public void foo(){ 
//... 
} 

---

P. S. Entiendo el punto aquí sobre API, pero los métodos simplemente "no son compatibles". Trabajan (y deben ser públicos para el acceso desde otros paquetes), pero no quieren molestar a documentarlas y responder preguntas sobre cómo usarlos cuando su funcionalidad no es relevante para los escenarios de uso compatibles. Un buen diseño puede significar moverlos a otra clase, pero lógicamente se refieren a los datos de la clase.

Answer 1

No si está utilizando la herramienta JavaDocs de Sun.

Ellos tienen a feature request para ello, pero que ha estado en baja prioridad desde 1997.

Puede escribir un doclet medida para superar esto, o utilizar una herramienta de 3 ª parte (DocFlex o tal).

Answer 2

Sí ... pero no en el buen sentido (tener métodos que son públicos que no son realmente "públicos" no es una gran práctica de diseño).

Puede seguir la sugerencia dada en this thread y marcar el método usando @deprecated luego cuando ejecuta javadoc use la opción -nodeprecated.

Editar: Como han notado otros, esto es no un curso de acción deseable. Esto va a resolver su problema, pero que realmente necesita volver a pensar qué es lo que quiere ocultar el método - dado una versión compilada de su código alguien todavía será capaz de ver su función; esconderlo en la documentación no oculta el método. Realmente quiero enfatizar aquí que los calificadores private, public y protected tienen un significado que debe considerar y utilizar de manera efectiva. No existe el método public "oculto".

Answer 3

La única razón por la que podría pensar que usted querría hacer esto sería "ocultar" el método en algún sentido, aunque solo sea en términos de documentación. Si lo hiciera, estaría diseñando la documentación para que se "rompa" en el sentido de que la documentación se rompe cuando se desactualiza y ya no refleja con precisión lo que hace la clase. Como el método aún forma parte de la API pública, en realidad no la está ocultando.

Si desea que un método no se use fuera de la clase o de algunos usuarios, hágalo privado o en paquete. Si esto es inconveniente y debe ser público, simplemente documentaría muy claramente las limitaciones de su uso, posiblemente con una convención de nomenclatura (por ejemplo, Python hace esto, hay nombres de entidad rodeados de guiones bajos, que puedes ver pero que son pretende ser más parte de la implementación de la clase que la API pública)

Answer 4

/** 
* Don't use this method <br> 
* <i>or all your data will be lost.</i> 
*/ 
public void foo(){ 
    //... 
} 

así, utilice una mejor explicación de por qué el usuario no debe utilizar este método ...
Recuerde que no es difícil encontrar cualquier método (público), utilizando un decompilador o la reflexión.