자바에서 주석 다는 방법: Javadoc 이란 무엇일까? (Feat. 위키피디아)

Javadoc 이란?

• 선 마이크로 시스템즈에서 개발한 문서 생성기이다.
• 자바 소스코드로 HTML 포맷의 API 문서를 생성한다.
• HTML 로 생성하는 이유는 하이퍼링크를 편하게 달기 위함이다.
• 컴파일 타임에는 모두 지워지니 성능 걱정은 할 필요 없다.
• 작성된 자바 코드를 잘 이해하고 유지보수 하기 위함이 목적이다.

역사

이전에는 소프트웨어에 대한 독립형 문서를 작성할 Technical writers 를 고용했는데, 문서와 소프트웨어의 싱크를 유지하는 것은 매우 어려운 일이었다. 그래서 문서 생성기인 Javadoc 이 쓰이게 되었다.

자바의 첫 릴리즈 이래로 Javadoc 은 계속 쓰였고, JDK의 새 릴리즈마다 업데이트 됐다.

다른 언어의 문서 시스템에서 @field 문법을 모방하였다.

기술적인 구조

Javadoc 주석의 구조

• /** 로 시작한다.
• 첫 줄은 메서드를 기술한다. 그 이후는 태그를 이용하여 설명하는 내용이다.
  • @param: 메서드의 파라미터들
  • @return: 메서드의 리턴값
  • @throw: 메서드가 던질 수 있는 예외
  • @see: 더 보기

유형별 Javadoc 살펴보기

클래스

//import statements

/**
 * @author     n00nietzsche@gmail.com
 * @version    1.0.0
 * @since      1.0.0
 */
public class Test {
  // class body
}

• 클래스의 바로 위에 온다.
• import 문보다는 아래에 와야 한다.

메서드

/**
 * 1줄 짜리 간결한 설명 ------- (1)
 * <p>
 * 긴 설명 ----------------- (2)
 * <p>
 * HTML 로 줄바꿈하며 이어지는 설명이 있으면 더 한다.
 *
 * @param - 변수 설명 텍스트 - (3)
 * @return - 반환 값 설명 텍스트
 */
public int methodName (...) {
  // method body with a return statement
}

• (1): 무슨 일을 하는지 짧고 간결하게 설명한다.
• (2): 모든 세부사항이 설명될 수 있는 공간이다. 작성하지 않아도 된다.
• (3): 태그를 이용해 input output 등을 설명할 수 있다.

Javadoc 은 결국 HTML 을 결과로 뱉어내므로, HTML 태그를 이용한 줄바꿈 등이 유효하다.

변수

/**
 * 변수에 대한 설명
 */
private int debug = 0;

• 메서드와 작성법이 비슷한데, (3)이 생략되었다.

변수에서 기피되는 패턴

/**
 * 포인트의 수평과 수직 거리이다.
 */
public int x, y; // 기피해야 함

• Javadoc은 각각의 변수를 읽어 생성된 HTML 페이지에 넣기에 권장되지 않는 형태이다.
• 한 줄의 여러 변수를 선언하는 것은 기피하자.

/**
 * 포인트의 수평 거리이다.
 */
public int x;
/**
 * 포인트의 수직 거리이다.
 */
public int y;

• 이렇게 작성하는 게 좋다.

Javadoc 태그들

아래의 Class, Interface, Enum, Field, Method와 같은 표기는 태그를 적용할 수 있는 타입을 나타낸다.

• @author n00nietzsche: 작성자를 기술한다.
  • Class, Interface, Enum
• {@docRoot}: 관련된 경로를 표현할 때 사용된다.
  • Class, Interface, Enum, Field, Method
• @version 1.0.0: 소프트웨어 버전 엔트리를 제공한다. 클래스, 인터페이스당 1개이다.
  • Class, Interface, Enum
• @since since-text: 언제 이 기능이 생겼는지 기술한다.
  • Class, Interface, Enum, Field, Method
• @see reference: 문서의 다른 요소로 가는 링크를 제공한다.
  • Class, Interface, Enum, Field, Method
• @param name description: 메서드 파라미터를 기술한다.
  • Method
• @return description: 메서드의 반환 값을 기술한다.
  • Method
• @exception classname description, @throws classname description: 이 메서드로부터 던져질 수 있는 예외를 기술한다.
  • Method
• @deprecated description: 더 이상 사용되지 않아 deprecated 됐음을 표기한다.
  • Class, Interface, Enum, Field, Method
• {@inheritDoc}: 오버라이드된 메서드에서 설명을 가져온다.
  • Overriding Method
• {@link reference}: 다른 심벌로 가는 링크를 제공한다.
  • Class, Interface, Enum, Field, Method
• {@linkplain reference}: {@link}와 동일한데, 링크의 레이블이 코드 폰트가 아니라 플레인 텍스트로 표시된다.
  • Class, Interface, Enum, Field, Method
• {@value #STATIC_FIELD}: 정적 필드의 값을 반환한다.
  • Static Field
• {@code literal}: 리터럴 텍스트를 코드 폰트로 포맷팅한다. <code>{@literal}</code>과 동일하다.
  • Class, Interface, Enum, Field, Method
• {@serial literal}: 기본 serializable 필드에 대한 문서 커멘트 내에서 쓰인다.
  • Field
• {@serialData literal}: writeObject(), writeExternal() 메서드에 의해 쓰인 데이터를 문서화한다.
  • Field, Method
• {@serialField literal}: ObjectStreamField 컴포넌트를 문서화한다.

@see와 {@link}가 헷갈린다면 see vs link 포스팅을 참고하자.

예제

• 메서드를 문서화 한 Javadoc의 예제이다.
• 공백과 문자열의 수는 컨벤션을 따라 작성되었다.

/**
 * 체스 움직임을 검증한다.
 *
 * 피스를 움직이기 위해 {@link #doMove(int fromFile, int fromRank, int toFile, int toRank)} 를 사용한다.
 *
 * @param fromFile file from which a piece is being moved
 * @param fromRank rank from which a piece is being moved
 * @param toFile file to which a piece is being moved
 * @param toRank rank to which a piece is being moved
 * @return 움직임이 유효하다면 true 를 반환한다. 그 외에는 false 를 반환한다.
 * @since 1.0
 */
 boolean isValidMove(int fromFile, int fromRank, int toFile, int toRank) {
   // ... body
 }

 /**
  * Moves a chess piece.
  *
  * @see java.math.RoundingMode
  */
  void doMove(int fromFile, int fromRank, int toFile, int toRank) {
    // ... body
  }