[Java, Spring] 코드 문서화를 위한 주석 규칙 알아보기

다수와 같이 프로젝트를 할 때 메모를 남기는 것은 필수라고 생각합니다. 

Swagger, Javadoc 등으로 메모한 내용들을 문서화할 수 있고, 평소에는 Swagger만 사용하다 프로젝트 내부에 조금 더 자세히 기록을 남기고 싶어 오늘은 Javadoc 코드 문서화하는 규칙을 알아보려고합니다 !

 

JavaDoc Tag와 작성 규칙

@version

구현체(클래스, 메소드, 변수 등)의 버전

@author

작성자

@deparecated

해당 구현체가 곧 삭제, 업데이트 중단을 의미

@since

해당 구현체가 추가된 버전

@see

외부 링크나 텍스트, 다른 필드나 메소드를 링크할 때 사용

@link

see와 동일한 기능, 참조에 대한 링크 제공

@exception

발생할 수 있는 Exception을 정의

@throws

코드에서 throw할 수 있는 예외상황 정의

@param 

메소드의 매개변수, 인자값을 설명

@return

반환값

@serial

Serializable Interface에 사용

@seriaDate

writeObject writeExternal 메소드로 작성된 추가적 데이터를 설명

@serialField

serialPersistnetFields 배열의 모든 필드에 사용

 

 

예시

public interface CargoShip {
   Stack<Supply> unload();

   /**
    *  제품을 화물선에 싣는다.
    *
    *
    * @version : 1.0.1
    * @author : chanhan
    * @param : 적재할 제품이며, null 값은 안됨.
    * @return : 용량이 작아 실을 수 없었떤 제품,
    *           모두 실었다면 empty
    * @throws : 제품이 null -> NullPointException
    * @see : CargoShip#getRemainingCapacity()용량 확인하는 함수
    * @see : CargoShip#unload() 제품을 내리는 함수
    */
   Queue<Supply> load(Queue<Supply> supplies);
   
   int getRemainingCapacity();
}