¿Uso de @see en JavaDoc?

110

¿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!

java methods javadoc

— Jeff
fuente

4

poner @seeen MethodB's javadoc y referencia MethodAporque 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 ...

— Mr_and_Mrs_D

1

Significa lo que generalmente significa en inglés: oxforddictionaries.com/us/definition/american_english/see (definición 1.4)

— stackexchanger

119

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 :

/**
 * ...
 * Works like {@link #methodB}, but ...
 */

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í.

— Paŭlo Ebermann
fuente

13

@seetambién es útil para vincular alternativas a los @Deprecatedmétodos.

— Mauve Ranger

1

@MauveRanger Dado que @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

— Christopher

10

@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.

— Rob Dawson
fuente

9

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 una javadocsecció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: @see

— ÁtomoCorazónPadre
fuente

2

no era yo, pero probablemente fue porque tenemos @inheritDoc docs.oracle.com/javase/6/docs/technotes/tools/solaris/…

1

la documentación de java para @see es realmente buena. debería ser el primero.

— dok

2

@vaxquis @inheritDoccopia la documentación de otra ubicación. Me imagino que describir detalles en lugar de agregar pelusas tiene sus usos.

— Nielsvh

@Nielsvg esta respuesta menciona eso 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 @inheritDoc y 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.

2

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

— Maruthi
fuente