JavaDoc
javadoc 공식 doc
https://docs.oracle.com/javase/8/docs/api/
cmd
java dir 이동 후
javadoc -d doc*.java
vscode
vscode extensions 에서 Javadoc Tools install -> javadoc Tools:Export Javadoc으로 생성
eclipse
프로젝트 Export 클릭 , Java -> Javadoc Next 클릭 , Javadoc.exe 경로 설정 및 기타 설정 후 export로 생성
javadoc 옵션
-d , 생선 된 문서의 대상 디렉토리 지정
$javadoc -d [dir 위치]
-author , @author 태그로 지정된 값 출력
-version @version 태그로 지정된 값 출력
$javadoc -auth [파일명]
$javadoc -version[파일명]
예를 들어보자
/**
* 해당 메소드관련 설정
*
* 주어진 관리자가 관리하는 carousel들의 정보를 가지고 있는 XML를 return한다.
* manager는 Manager Class의 instanceName이 된다.
*
* @version 0.1
* @author woohot
* @return String
* @param str <code>String</code> str
* @throws Exception
*/
public String docText(String str) throws Exception{
return str;
}
주석의 구성
설명문, 태그 섹션
설명문은 클래스 또는 메소드 등에 대해 간략하게 설명한 글이고, 설명문은 여러줄을 작성할 수 있다.
주석의 시작부분에서 첫번째 태그 섹션이 나타날 때까지가 설명문이 되고
Html문으로 해석되기 때문에 단순히 행을 바꿔 작성하여도 줄바꿈이 되지 않고 명시적으로
<br>을 작성해서 줄바꿈을 해야한다.
태그 섹션으로 첫 번째 문자가 @로 시작한다.
태그 섹션은 하나의 주석에 여러 종류를 동시에 작성 할 수 있다.
또한 태그 섹션이 작성된 후에는 '설명문'을 작성 할 수 없다.
Javadoc 태그
- 종류
@version , @since , @author , @see , @deprecated , @param , @return , @throws , @exception , {@link} , {@linkplain}
@version , @since
소프트웨어의 버전을 지정하기 위해 사용
@since는 도입 된 버전을 지정할 경우 사용
/**
* @since 0.1
* @version 1.0
* @version Project 1.0.1
*/
@auth
클래스,인터페이스,메소드 등 작성하고 작성자를 나타낸다 .
여러번 사용 가능
/**
*
* @auth woohot
* @auth woohot2
* @param manager <code>String</code> manager
* @throws Exception
*/
@see
관련 항목으로 외부 링크 또는 텍스트를 표시하거나, 다른 필드나 메소드에 대한 모든 참조 링크를 나타내는 경우에 사용.
여러번 사용 가능
/**
* @see 0.1
* @see package.Class#method(Type, Type,...)
* @see package
*/
@deprecated
클래스나 메소드 등을 더 이상 사용을 권장하지 않는 경우에 사용
/**
* @deprecated 다른 메소드로 대체예정 { @link #docTest(String)}
*/
@param
매개 변수에 대한 설명을 표시 할 때 사용
/**
* @param whereCondition <code>String</code>
* @param manager <code>String</code> manager
* @param mapIds <code>String[]</code> map instancenames
*/
@return
반환 값에 대한 설명(데이터 유형 및 범위 등)을 표시 할 때 사용
/**
* @param whereCondition <code>String</code>
* @param manager <code>String</code> manager
* @param mapIds <code>String[]</code> map instancenames
* @return MainMapInstList MAPINS array
*/
@throws @exception
발생할 수 있는 예외에 대한 설명을 표시 할 때 사용
이름만 다를뿐 동일하게 사용
/**
* 파일 읽기
* @throws java.io.IOException 입출력 관련
* @throws java.lang.SecurityException 보안 관련
*/
{@link}
다른 Javadoc 태그 중에 참조 링크를 표시 할 경우에 사용
이 태그는 인라인 태그라고 하며, {}로 묶어 사용하는 주석을 설명문 안이나 다른 블록태그 안의 문자열의 부분에 사용
{@linkplain}
{@link}태그와 사용방법은 동일
Javadoc 태그에서 문자열을 표시 할 위치에 참조링크를 표시 할 경우에 사용
{@link}태그를 사용하는 경우 연결 문자열은 코드 텍스트로 표시되는 반면, {@linkplain}태그의 경우는 링크가 된 문자열을 일반텍스트로 표시되는 점이 다름
/**
* 이름 설정
* 반환은 {@link Sample #getName() getName}을 참조
*@param name 이름
*/
/**
* 이름 반환
* 설정은 { @link #setName(String)}을 참조
* @return 이름을 String으로 반환
*/
@{code}
Javadoc에 예제 코드 작성시 사용
/**
* Javadoc 샘플 클래스<br>
* <pre>
* { @code
* Foo foo = new Foo();
* foo.foo();
* }
* </pre>
*/
#참고
https://docs.oracle.com/javase/8/docs/api/