javadoc

본 포스팅은 javadoc 을 알아보는 내용입니다.

1. javadoc 이란?

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

2. javadoc 주석의 구조

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

3. 유형별 javadoc 살펴보기

1) 클래스

• 클래스의 바로 위에옵니다.
• import문 보다는 아래에 와야 합니다.

    //import statements

    /**
     * @author     cho
     * @version    1.0.0
     * @since      1.0.0
     */
    public class Test {
    // class body
    }

2) 메서드

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

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

3) 변수

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

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

4. 참고문헌

• https://docs.oracle.com/javase/8/docs/technotes/tools/windows/javadoc.html