¿Cuándo lo uso @seecuando trato con JavaDocs? Cual es su uso?
Por ejemplo, si MethodAlas llamadas MethodBa continuación, tengo que poner @seeen MethodBjavadoc 's y referencia MethodAporque es lo que se llama, o tengo que poner una referencia a MethodBpartir de MethodAya que está llamando. He leído el material sobre el tema @seeen el sitio web de Oracle y me parece increíblemente vago, dice que significa "ver también", ¡pero no realmente lo que eso significa!
@seeenMethodB's javadoc y referenciaMethodAporque es lo que se llama -> ¿Cómo sería siempre posible conocer todos los métodos que se llaman a uno de sus métodos? Incluso si esto es posible (digamos que un método privado se usa solo una vez), vincular de la persona que llama a la persona que llama suena al menos extraño ...Respuestas:
Sí, es bastante vago.
Debe usarlo siempre que los lectores de la documentación de su método puedan ser útiles para ver también algún otro método. Si la documentación de tu método A dice "Funciona como método B pero ...", entonces seguramente deberías poner un enlace. Una alternativa a
@seesería la{@link ...}etiqueta en línea :Cuando el hecho de que el método A llame al método B es un detalle de implementación y no existe una relación real desde el exterior, no necesita un enlace aquí.
fuente
@seetambién es útil para vincular alternativas a los@Deprecatedmétodos.@seees bastante vago, para las cosas obsoletas me parece más útil hacer algo más explícito, como:@deprecated since X.Y.Z; use {@link #alternateMethod()} instead@see es útil para obtener información sobre métodos / clases relacionados en una API. Producirá un enlace al método / código referenciado en la documentación. Úselo cuando haya un código relacionado que pueda ayudar al usuario a comprender cómo usar la API.
fuente
Un buen ejemplo de una situación en la que
@seepuede ser útil sería implementar o anular una interfaz / método de clase abstracta. La declaración tendría unajavadocsección que detalla el método y el método reemplazado / implementado podría usar una@seeetiqueta, refiriéndose a la base.Pregunta relacionada: ¿ Escribiendo javadoc adecuado con @see?
Documentación de Java SE:
@seefuente
@inheritDoccopia la documentación de otra ubicación. Me imagino que describir detalles en lugar de agregar pelusas tiene sus usos.the overridden/implemented method could use a @see tag, referring to the base one., y para eso es exactamente@inheritDoc; En mi opinión, es mejor incluir la descripción de la clase base palabra por palabra@inheritDocy complementarla según sea necesario, que consultarla mediante@see: consulte (¡sic!) Stackoverflow.com/questions/11121600/… ; muchos desarrolladores (yo incluido) prefieren tener todos los detalles de implementación en un solo lugar, en lugar de una cadena interminable de enlaces ascendentes que conducen hacia arriba a través de una jerarquía de herencia.Utilizo @see para anotar métodos de una clase de implementación de interfaz donde la descripción del método ya se proporciona en el javadoc de la interfaz. Cuando hacemos eso, noto que Eclipse saca la documentación de la interfaz incluso cuando estoy buscando el método en la referencia de implementación durante el código completo
fuente