JavaDoc에서 @see 사용?

110

@seeJavaDocs를 다룰 때 언제 사용 합니까? 그 사용법은 무엇입니까?

예를 들어 경우 MethodA통화 MethodB후 내가 넣어해야합니까 @see에서 MethodB의 Javadoc을 참조 MethodA그게라는 것 때문에, 또는 내가에 대한 참조를 넣어해야합니까 MethodB에서 MethodA그것을 부르고 있기 때문이다. 나는 @see오라클 웹 사이트에 대한 내용 을 읽었고 믿을 수 없을 정도로 모호한 것 같습니다. "도보 기"를 의미하지만 실제로는 그 의미가 아닙니다!

java methods javadoc

— 제프
소스

4

넣어 @see에서 MethodBjavadoc의 참조의 MethodA그게라는 것 때문에 > 지금까지 가능할 것이다 어떻게 방법 중 하나를 호출하는 모든 방법을 알고 -? 이것이 가능하더라도 적어도 발신자 소리에 호출자에서 이상한 ... 링크 (private 메소드는 한 번만 사용하는 말)

— Mr_and_Mrs_D

1

일반적으로 영어로 의미하는 바를 의미합니다. oxforddictionaries.com/us/definition/american_english/see (정의 1.4)

— stackexchanger

119

네, 아주 모호합니다.

당신은 당신의 방법에 대한 문서를 읽는 독자들이 다른 방법을 살펴 보는 것이 유용 할 때마다 그것을 사용해야합니다. methodA의 문서에 "Works like methodB but ..."가 표시되어 있으면 반드시 링크를 넣어야합니다. 대신 @see인라인 {@link ...}태그가 있습니다.

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

methodA가 methodB를 호출한다는 사실이 구현 세부 사항이고 외부와의 실제 관계가없는 경우 여기에 링크가 필요하지 않습니다.

— Paŭlo Ebermann
소스

13

@see@Deprecated메서드의 대안에 연결하는데도 유용 합니다.

— Mauve Ranger

1

@MauveRanger @see꽤 모호 하기 때문에 더 이상 사용되지 않는 항목의 경우 다음과 같이 좀 더 명시적인 작업을 수행하는 것이 더 유용하다고 생각합니다.@deprecated since X.Y.Z; use {@link #alternateMethod()} instead

— Christopher

10

@see는 API의 관련 메서드 / 클래스에 대한 정보에 유용합니다. 문서에서 참조 된 메서드 / 코드에 대한 링크를 생성합니다. 사용자가 API 사용 방법을 이해하는 데 도움이 될 수있는 관련 코드가있을 때 사용하십시오.

— 롭 도슨
소스

9

@see유용 할 수 있는 상황의 좋은 예 는 인터페이스 / 추상 클래스 메서드를 구현하거나 재정의하는 것입니다. 선언 javadoc에는 메서드를 자세히 설명하는 섹션 이 있으며 재정의 / 구현 된 메서드 @see는 기본 태그를 참조 하는 태그를 사용할 수 있습니다 .

관련 질문 : @see로 적절한 javadoc 작성?

Java SE 문서 : @see

— AtomHeartFather
소스

2

내가 아니었지만 아마

1

@see에 대한 자바 문서는 정말 좋습니다. 먼저해야합니다.

— dok

2

@vaxquis @inheritDoc는 다른 위치에서 문서를 복사합니다. 보풀을 추가하는 것보다 세부 사항을 설명하는 데 용도가 있다고 생각합니까?

— Nielsvh

이 답변을 @Nielsvg하는 것을 언급 the overridden/implemented method could use a @see tag, referring to the base one.- 그게 정확히 무엇을 @inheritDoc위한 것입니다; IMO는에 의해 그대로 기본 클래스의 설명을 포함하는 것이 좋습니다 @inheritDoc 과 필요에 의해 그것을 참조하는 것보다, 그것을 보충 @see(! 원문) - 참조 stackoverflow.com/questions/11121600/... ; 많은 개발자 (저를 포함) 는 상속 계층 구조를 통해 위쪽으로 이어지는 상향 링크 체인을 끊지 않고 한곳에서 모든 구현 세부 정보를 갖는 것을 선호 합니다.

2

인터페이스의 javadoc에 이미 메소드에 대한 설명이 제공되어있는 인터페이스 구현 클래스의 메소드에 주석을 달기 위해 @see를 사용합니다. 그렇게 할 때 코드가 완료되는 동안 구현 참조에서 메서드를 찾을 때에도 Eclipse가 인터페이스의 문서를 가져 오는 것을 알 수 있습니다.

— 마루티
소스