[Java] Javadoc 주석 문법 (Javadoc comment syntax and usage : tag)

◽ Java language/JavaDoc

[Java] Javadoc 주석 문법 (Javadoc comment syntax and usage : tag)

JavaDoc comment syntax

평소에는 별로 쓸 일이 없었는데 최근에 Proxy Socket관련 오픈소스 가지고 만드는 프로그램이 있는데 사람들이 많이 쓰지 않는 오픈소스라 그런지 레퍼런스도 없고 직접 이해하고 구현해야하는 경우가 대부분이라. 주석을 읽는 경우가 너무나도 많다. 덕분에 기존 자바(JDK) 주석을 보는데에도 예전보다는 주석 구조가 더 이해가 빨라져서 인지 빠르게 읽어진다.

이러한 주석에 더 익숙해지기 위해서 직접 자바독을 써보려고 하는데 개행처리라던지 약간의 Syntax가 있어서 정리를 하려고 한다.

위키백과 : Javadoc (원래 JavaDoc )은 Java 소스 코드 에서 HTML 형식의 API 문서 를 생성 하기 위해 Sun Microsystems 에서 Java 언어 (현재 Oracle Corporation 소유 )용으로 만든 문서 생성기 입니다.

1. 주석 처리

자바에서는 총 3가지의 주석처리 방법이 있는데, JavaDoc에서 쓰이는 주석은 "/** */"이다. 기존의 주석과 다른점은 앞에 "**"가 두개가 있다는 점이 차이점이라고 할 수 있겠다. 아래에서 적용할 Syntax들은 "/** */"안에서만 적용되는 것이라고 생각하면 되겠다.

아래에 소개할 Syntax를 소개하는 가장 큰 이유는 문서화 버튼을 눌렀을 때 예뻐(?)보인다. 아래 그림 참조.


주석 그대로의 모습	Render 했을 시 주석 ( IntelliJ에서 기본적으로 제공함 )

태그(@) 종류

위에서 보이는 태그들이 있는데 "@param, @return"이 있다. 같은 태그를 각각 쓰게되면 하나로 묶여 렌더링이 되며, "@return"의 경우 "@param"과 비슷하게 쌍따옴표가 나오면서 설명 할 수 있는 기본적인 구조가 제공된다.

@author	코드에 기여를 한 사람 명시.	@deprecated	사용자에게 클래스 또는 메서드가 더 이상 사용되지 않음(추천하지 않음)을 알리는 용도이며 자바독 생성 시 가장 위로 정렬이 됨.
@param	파라미터에 대한 설명이 필요할 때.	@return	리턴값에 대한 설명.
@see	참조 할 문서 표시	@link	@see에 내용으로 보통 쓰인다. ex) {@link Class#function()}
@throws	예외에 대한 설명이 필요할 때.	@overide	오버라이드에 대한 명시가 필요할 때.
@since	코드 버전을 명시가 필요할 때.