javadoc은 html을 따로 작성하지 않고도 소스 코드에 작성된 코멘트를 따라 문서를 만들 수 있다. 또한 Javadoc에 따른 형식으로 작성해 두면 일반적인 주석으로 읽을 수 있을 정도로 아무런 위화감 없이 쉽고 간단한 형식으로 되어있고 IDE에서 사용할 경우 해당 메서드에 마우스를 올리면 param / return 값, 메서드 정의, 설명 등 해당메서드에 대한 정보를 제공해준다는 면에서 매우 유용하다.
나는 단지 비즈니스 로직을 구현하기 전 인터페이스를 통해 메서드를 정의할 때 어떤 기능과 역할을 하는지 작성하고 싶어서 작성하는 정도로 생각했었다.
정식명칭은 'JavaDoc'이라고 한다:)
JavaDoc 애너테이션 정리
@author : 코드 소스 작성자
@deprecated : 해당 클레스(구현체)의 삭제 또는 지원이 중단되는 것을 알려줌
@exception : 예외처리할 수 있는 것들을 정의, 알파벳 순
@param : 매개변수 메서드, 생성자 설명
@return : 리턴값 설명
@see : 파일이 참조하는 다른 클래스와 메서드 등
@serial : Serializeable 인터페이스에 사용
@serialData : writeObject writeExternal 메소드로 작성된 데이터 설명
@serialField : serialPersistnetFields 모든 배열에 사용됨
@since : 해당 클래스가 추가된 버전
@throws : @exception처럼 예외처리하는 것들을 정의
@version : 구현체, 패키지 버전 명시
JavaDoc 사용예시
public interface UserServiceInter {
/**
* <h2>access token/refresh token 재발급을 요청한다.</h2>
* </br>
* @param reissue name, email, password, phone
* @return ReissueResponseDto HTTP 상태 코드, 응답 메시지, 새롭게 발급된 Access token/Refresh token
*/
ReissueResponseDto reissue(ReissueDto reissue);
}🚨 @author 사용은 지양함
이유는 아래의 블로거에 자세히 기술되어있다.
간단히 요약하자면 git으로도 시간, 작성자등 관리가 가능한데 구지 이중으로 작성해둘 필요가 있냐, 혼란만 가져올 뿐이다라는 이유다.
