[JAVA] Javadoc의 @See, @link, @inheritDoc 태그 살펴보기

main

 

Javadoc은 Java 소스 코드에서 HTML 형식의 최신 Java 문서를 생성하는 좋은 방법입니다.
Javadoc 주석 중 @see, @link, @inheritDoc 태그에 대해서 알아보겠습니다.

@see

참조를 가리키는 링크나 텍스트 항목이 필요할 때 @see 태그를 사용합니다.
이 태그는 참조에 "참조" 제목을 추가합니다. 문서 주석에는 수많은 @See 태그를 사용할 수 있습니다. 또한 모두 같은 제목으로 그룹화할수도 있습니다. Oracle 문서에서는 사용 방법에 대한 자세한 가이드를 제공합니다. 이 태그는 유효하며 패키지, 개요, 생성자, 클래스, 인터페이스를 포함한 모든 문서 주석에서 사용 가능합니다. @see 태그에는 3가지 변형이 있습니다.

 

@See 태그의 형식

@see reference

 

@See 태그의 기분 형식

/**
 * @see <a href="https://docs.oracle.com/en/java/">Java Dcoumentation</a>
 */

@see "text-string"

어떠한 유형의 링크도 생성하지 않고 텍스트 문자열에 대한 텍스트 항목을 추가합니다. 문자열은 책 페이지나 추가 컨텍스트에 제공해야 하는 다른 추가 정보를 참조할 수 있습니다. Javadoc 도구는 첫 번째 문자로 큰따옴표("")를 찾아 텍스트 문자열을 다른 모든 경우와 구별합니다.

/**
 * @see "This method performs some function."
 */
public void someMethod() {
  // do Something...
}

 

이는 다음과 같이 렌더링 됩니다.

@see "text-string" 렌더링

@see <a href="URL">라벨</a>

URL을 정의하는 링크를 추가할 경우 사용됩니다. URL은 상대적 또는 절대적 URL 값일 수 있습니다.

Javadoc 도구는 첫 번째 문자로 보다 작음 기호(<)를 보고 URL #값 을 정의하는 링크를 추가하여 텍스트 문자열을 다른 모든 경우와 구별합니다. URL # 값은 상대적 URL입니다.

Javadoc 도구는 첫 번째 문자로 보다 작음 기호(<)를 찾아 다른 경우와 구별합니다.

/**
 * @see <a href="http://www.baeldung.com">Baeldung</a>
 */
public void someMethodV2() {
  // do Something...
}

 

이렇게 할경우 다음과 같이 렌더링 됩니다.

@see <a href="URL">라벨</a> 렌더링

 

@see package.class#member 라벨

함수를 정의하는 링크를 추가할 경우 사용합니다. 레이블은 선택 사항이며 정의되지 않은 경우 클래서의 원래 멤버 이름을 사용합니다. -no 한정자 옵션은 표시되는 텍스트에서 패키지 이름을 제거합니다.

package.class#member는 패키지, 클래스 인터페이스 또는 필드 이름과 같은 요소 이름을 참조합니다.

/**
 * @see String#toLowerCase() convertToLowerCase
 */
public void addingSeeToAMethod() {
  // do Something...
}

 

이에 해당되는 생서되는 HTML은 다음과 같습니다.

<dl> 
<dt><b>See Also:</b> 
<dd><a href="../../java/lang/String#toLowerCase()"><code>convertToLowerCase<code></a> 
</dl>

 

따라서 브라우저에서는 다음과 같이 출력됩니다.

@see package.class#member 라벨 렌더링

@link

@link는 인라인 태그입니다. @link 태그의 형식은 간단합니다.

{@link  package.class#member  label}

 

@link 태그를 사용하는 예는 다음과 같습니다.

/**
 * Use the {@link String#equalsIgnoreCase(String) equalsMethod} to check if two strings are equal.
 */

 

위 예는 눈에 보이는 텍스트 레이블이 있는 인라인 링크를 산입합니다. 텍스트 레이블은 지정된 패키지, 클래스 또는 멤버 이름에 대한 설명서를 가리킵니다. 이 태그는 개요, 패키지, 클래스, 매서드, 필드 등 모든 곳에서 사용가능 합니다. @return, @param, @deprecated와 같은 태그의 텍스트 부분 내부에서도 사용 가능합니다. @see 태그와 유사한 이유는 둘 모두 동일한 참조를 필요로 하고 package.class#member 및 label에 대해 동일한 구문을 허용하기 때문입니다.

 

위의 예에서 생성된 HTML은 다음과 같습니다.

Use the <code>equalsMethod</code> to check if two strings are equal.

 

브라우저에서는 다음과 같이 렌더링 됩니다.

@link 렌더링

@see와 @link의 유사점

@see 및 @link 태그를 클래스, 패키지 또는 메서드에서 여러 번 사용가능 합니다. @see 태그는 외부 링크, 클래스 또는 메서드를 가르키는 참조를 선언합니다. @link 태그는 인라인 링크를 선언하거나 다른 블록 태그와 대조적으로 여러번 사용할 수도 있습니다. @see 및 @link 태그의 구문을 보여주는 다음과 같습니다.

/**
 * Use {@link String#toLowerCase()} for conversion to lower case alphabets.
 * @deprecated As of Java 1.8 {@link java.security.Certificate} is deprecated.
 * @return {@link String} object
 * @see <a href="http://www.baeldung.com">Baeldung</a>
 * @see String#hashCode() hashCode
 */
public String someMethod() {
  // perform some function
  return "";
}

@see와 @link의 차이점

1. 둘 모두 다른 태그에 속함

 

문서 주석은 두 가지 유형으로 분류할 수 있습니다.

• 블록 태그
• 인라인 태그

블록 태그는 줄의 시작 부분에 나타내는 @tag 형식을 갖습니다. 이는 선행 별표, 공백 및 구분 기호(/**)를 무시합니다. @see는 블록 태그의 한 예 입니다.

인라인 태그는 중괄호 안에 나타나며 [@tag] 형식을 갖습니다. 그리고 텍스트가 허용되는 모든 곳에서 허용되고 해석되어야 합니다. 인라인 태그와 함께 다른 태그도 사용할 수 있습니다. 설명이나 주석의 어느 곳에나 존재할 수 있습니다.

/**
 * Some description here.
 *
 * @see java.lang.Object
 * @return  This will return {@link #toString() string} response.
 */

 

2. @see 및 @link 태그 표시

 

@see와 @link 태그의 주요 차이점은 하나는 인라인 링크를 생성하는 반면, 다른 하나는 링크를 "See Also"섹션에 표시한다는 것입니다. 또한 @link 태그는 나머지 인라인 텍스트와 구분하는 중괄호로 시작하고 끝납니다.

@see태그는 블록 태그이므로 명시적으로 만들 것입니다.

@see 및 @link 태그에 대한 출력을 표시하는 것은 다음과 같습니다.

/**
 *
 * Use {@link String#toLowerCase()} for conversion to lower case alphabets.
 * @deprecated As of Java 1.8 {@link java.security.Certificate} is deprecated.
 * @return {@link String} object
 * @see <a href="http://www.baeldung.com">Baeldung</a>
 * @see String#hashCode() hashCode
 */
public String someMethod() {
  // perform some function
  return "";
}

 

위 주석은 다음과 같이 렌더링 됩니다.

@see 및 @link 태그 표시 렌더링

3. @see 및 @link 태그 사용

 

블록 태그는 독립적으로 사용되며 다른 태그와 함께 사용할 수 없습니다. 반면, 인라인 태그는 문서 주석 내부 또는 인라인 링크로 사용됩니다. @link 태그를 다른 블록 태그와 함께 사용할 수도 있습니다.

@link 태그를 다른 블록 태그와 함께 사용하는 예는 다음과 같습니다.

/**
 * Some description here.
 *
 * @see java.lang.Object
 * This is a {@link #getClass() } method.
 * @see #getClass() Use {@link #toString()} for String conversion.
 * @deprecated As of JDK 1.1, replaced by {@link #someMethod()}
 */

@inheritDoc

@see 태그와 달리 @inheritDoc는 인라인 태그입니다.

{@inheritDoc}

 

@inheritDoc은 객체 지향 프로그래밍에서 상속의 개념을 채택합니다. 슈퍼 클래스나 인터페이스에서 유사한 요소의 설명서를 상속합니다. 즉 공통 설명서를 반복할 필요가 없습니다.

태그는 메서드의 주요 설명 블록과 매서드 태그의 @return, @throws, @param의 텍스트 인수에서 사용할 수 있습니다.

 

@inheritDoc은 로컬에서 사용 가능한 슈퍼클래스나 인터페이스에서만 상속할 수 있습니다. 이를 확인하기 위해 Runnable과 유사한 새로운 인터페이스를 만들어 보겠습니다.

public interface MyRunnable {
    /**
     * Runs this operation.
     */
    void run();
}

 

인터페이스에는 run() 메서드에 대한 간단한 설명이 있습니다.

새로운 클래스 TimeOutputtterRunable을 생성하여 인터페이스를 구현하면 다음과 같습니다.

public class TimeOutputterRunnable implements MyRunnable{
    /**
     * {@inheritDoc}
     * Outputs current time in epoch milliseconds when run.
     */
    public void run(){
        System.out.println(System.currentTimeMillis());
    }
}

 

클래스는 인터페이스의 유일한 메서드를 구현합니다. @inheritDoc을 사용하여 인터페이스의 설명서를 삽입합니다. 또한 이 구현에 대한 추가 텍스트도 추가했습니다. 결과적으로 Javadoc에서 부모 인터페이스의 설명서와 이 클래서의 텍스트를 모두 확인 할 수 있습니다.

@inheritDoc 상속한 class 렌더링

 

 

 

@see, @link, @inheritDoc에 대해서 알아보았습니다.

@see 태그는 참조를 가리키는 링크나 텍스트를 표시할 때 사용하고, @link 태그는 텍스트나 다른 태그의 링크를 인라인으로 설명을 하며, @inheritDoc는 인터페이스의 javadoc을 가져올 수 있었습니다.

@see와 @link 함수는 Javadoc에 교차 참조를 넣기 위한 것이며, @inheritDoc은 슈퍼 클래스 또는 인터페이스에서 Javadoc을 가져오기 위한 것입니다.

 

 

 

 

 

 

 

 

 

 

 

 

출처: https://www.baeldung.com/javadoc-see-vs-link
참고: Oracle 문서