[Javadoc] 문서화

언제까지 문서를 직접 작성할꺼야? Javadoc로 문서를 한 번에 끝내자!

Javadoc이란 주석으로 작성된 코드 문서를 HTML 문서로 만들어주는 도구다.

필자는 Gradle를 사용했기 때문에, IDEA Terminal에서 아래의 명령어를 날려주면 자동으로 문서화된다.

./gradlew javadoc

생성된 문서는 /build 디렉토리에 만들어지며, app/build/docs/javadoc/index.html을 브라우저에서 열면 문서를 확인할 수 있다.

index.html을 열어봤는데 딱히 내용이 없다고?

 

Javadoc는 소스 코드에 작성한 주석을 기반으로 문서를 만들어준다. 그래서, Javadoc 용 주석을 사용해야 한다. 

보통 주석을 작성함에 있어서 사용하는 주석은 아래와 같다. 

// 이 주석은 한 줄을 주석 처리한다.
/*
 * 이 주석은 여러 줄을 주석 처리한다.
 */

Javadoc는 좀 다르다. 아래와 같이 주석의 시작이 "/**" 인 것을 볼 수 있다.

/**
 * Access token을 복호화합니다.
 *
 * @param token 토큰
 * @return 복호화된 토큰의 내용
 */

어디서 많이 보던 주석들이다. 여러 가지 Helper method 사용법을 보기 위해 command+b 혹은 F3 등을 눌러서 보던 것들이다. Javadoc가 바로 이런 것들을 정리하여 자동으로 문서화 해주는 것이다.

예) java.util.List의 Javadoc

Javadoc를 잘 활용하기 위해서는 항상 읽기 쉽고 명료한 주석을 습관처럼 남겨야 한다.

주석은 항상 내가 보는 것이 아닌 다른 독자(동료)를 생각하고 작성하도록 하자!