[MEJ-013] javadoc 실습 및 생성 방법 정리

based on: #217 by @undeadtimo

api를 작성할때 문서화 주석을 작성해야 한다는 것만 알았지 실제로 javadoc을 생성해본 적이 없어서 문서화 주석이 아닌 단순 주석처럼 사용하고 있었는데, 직접 실습해 볼만한 부분을 탐구하고 정리해주셔서 감사합니다.

만일 부모 클래스의 문서화 주석을 상속받고 싶지 않고 그대로 보여주고 싶다면 @inheritDoc 대신 @see 태그를 사용하여 링크를 걸어줄 수 있다.

이 부분을 읽고 inheritDoc 어노테이션을 사용했을 때와 see 어노테이션을 사용했을 때를 직접 비교해보았는데, 링크를 통해 Parent 클래스의 메서드로 바로 이동할 수 있을 뿐 아니라 IDE에서 메서드에 hover했을때 띄워지는 설명 또한 다르게 보여지는 것으로 확인했습니다!

InheritDoc 사용시
see 사용시

javadoc 생성 방법 2가지 정리

제가 실습했던 javadoc 생성 방법은 2가지로, intelliJ를 사용한 생성과 터미널 명령어를 통한 생성입니다. javadoc을 생성하기에 앞서 모든 클래스, 인터페이스, 메서드, 필드 선언에 대하여 문서화 주석을 단 상황으로 가정합니다.

intelliJ

프로그램 상단바 Tools - Generate JavaDoc
생성할 문서 설정을 완료한다.
- 저는 테스트코드는 제외하려고 Include test sources 체크 해제했습니다. (캡쳐 이미지의 Test 라고 하는 내용들은 프로젝트명으로, 테스트코드와 무관합니다)
- Command line arguments에는 -encoding UTF-8 -charset UTF-8 -docencoding UTF-8를 입력하세요.
생성에 성공하면 javadoc이 자동으로 브라우저에 열린다.
- 이 경우, 최상위 디렉터리에 관련 파일들이 마구 생성된다... 지저분하다

gradlew 를 사용한 명령어 - 프로젝트 빌드 도구가 gradle인 경우

cmd(windows) 또는 터미널(Linux/MacOs)을 연다.
프로젝트 최상위 디렉터리로 이동했습니다.
자바 문서화 명령어를 입력한다.
```
./gradlew javadoc
```
- 이 경우, build/docs/javadoc 또는 docs 디렉토리에 HTML 파일들을 확인하면 된다.

스스로 처음 해보는 부분이다보니 이미 아시는 내용일 수 있지만 실습한 내용을 토대로 정리해보았습니다! 이번주도 고생하셨습니다 :)

문서화 작성 방법만을 알고 있었는데, javadoc을 생성하는 여러 방법을 정리해주셔서 감사합니다. 문서화 주석 작성 방법에 이어 javadoc을 생성하는 방법까지 같이 익히게 되어 실제로 유용하게 사용할 수 있게 되었습니다.

다만, Intellij IDE에서는 한글이 깨지지 않도록 -encoding UTF-8 -charset UTF-8 -docencoding UTF-8를 설정하여 에러가 발생하지 않았지만,

터미널 환경에서 ./gradlew javadoc 명령어를 실행하니 인코딩 설정이 되어있지 않아. 오류가 발생하여 정상적으로 javadoc을 생성할 수 없었습니다.

javadoc{
    source = sourceSets.main.java.srcDirs
    options.encoding = 'UTF-8'
}

그렇기에 위 설정을 build.gradle에 작성하여 build 작업을 마친 후 다시 터미널 환경에서 javadoc 생성을 시도하자 오류없이 javadoc이 생성되었습니다.

코드를 깔끔하게 구성하는 것부터 이해하기 쉽게 주석을 첨부하는 것까지 다른 프로그래머 및 클라이언트와의 원활한 협업을 위한 과정이 많이 존재하여 그 중요성이 항상 대두됩니다.

그렇기에 친숙한 방식으로 코드를 이해시키는 문서화 주석 작성법을 숙달하여야, 원활한 정보 전달을 이룩하고 효율적인 작업을 이끌 수 있을 것입니다.

바쁘신 와중에도 추가적인 자료 제공에 대해 다시금 감사드립니다.

glenn-syj / more-effective-java