자바독 치트 시트(Javadoc cheat sheet)

자바독으로 문서화할 때 많이 사용하는 구문.

Javadoc

Java 소스에 문서화를 하는 방법으로 클래스나 메소드에 주석으로 기술한 내용을 javadoc 명령어나 또는 이를 이용한 빌드 툴(maven 의 site phrase등)을 사용하여 문서화할 수 있다. 문서화할 주석을 달 경우

/** 두 개로 시작하고 */ 로 끝나야 한다. 특별한 키워드는 @keyword 형식으로 작성한다.

@author

소스의 저자를 의미하며 이클립스에서는 기본 값으로 윈도 로그인 id 를 사용한다. 버전 관리 시스템에 변경 이력이 남아있고 한 소스를 여럿이 고치는 경우가 많으므로 회사에서는 사용하지 않는다.

스프링 프레임워크의 경우 소스마다 Juergen Hoeller 라는 분 이름이 있는 것을 볼 수 있다.

/**
 * Converts an array to a Collection.
 *
 * <p>First, creates a new Collection of the requested target type.
 * Then adds each array element to the target collection.
 * Will perform an element conversion from the source component type
 * to the collection's parameterized type if necessary.
 *
 * @author Keith Donald
 * @author Juergen Hoeller
 * @since 3.0
 */
 final class ArrayToCollectionConverter implements ConditionalGenericConverter {

{@link}

내/외부 클래스나 메소드등을 연결할 때 사용하며 다른 키워드(@deprecated 등)와 같이 사용해야 하는 경우 유용. 사용 예는 바로 아래 예제 참고

@deprecated

오래되서 더 이상 사용을 권장하는 않는 클래스, 메소드, 인터페이스에 사용하며 @Deprecated 애노테이션과 같이 사용하면 더욱 유용함.

http://stackoverflow.com/questions/9031832/how-to-declare-or-mark-a-java-method-as-deprecated

 /**
 * Does some thing in old style.
 *
 * @deprecated use {@link #newMethod()} instead.  
 */
public void oldMethod() {
}
 
public void newMethod() {
}

@see

다른 클래스나 메소드를 참고할 경우 사용.

@see className

클래스 이름 연결

/** 
  * 클래스 설명
  * 
  @see org.springframework.core.convert.ConverterNotFoundException 
  */

@see #method - 클래스내 메소드나 변수 연결

#method : 현재 클래스의 메소드나 변수 연결
MyClass#method : MyClass 클래스의 메소드나 변수 연결
my.package.MyClass#method : my.package 에 있는 MyClass 클래스의 메소드나 변수 연결

	/**
	 * @see #priMethod()
	 */
	public void method2() {		
	}	
	private void priMethod() {		
	}

여러 개의 메소드가 오버로딩 되어 있을 경우 파라미터를 같이 기술

	/**
	 * @see #priMethod(int, String)
	 */
	public void method2() {

	}	
	private void priMethod() {		
	}

	private void priMethod(int i, String s) {		
	}

외부 URL 링크

HTML 의 a href 태그를 사용하여 외부 URL 을 링크

http://stackoverflow.com/questions/1082050/linking-to-an-external-url-in-javadoc

/**
 * @see <a href="http://google.com">http://google.com</a>
 */

작성된 외부 링크는 다음과 같이 표시됨.

See Also:

http://google.com

@since

클래스나 메소드나 언제부터 있었는지 여부를 지정. API 로 제공하는 경우 API 사용자가 어느 버전의 라이브러리에서 이 기능를 제공하는지 알아야 의존성을 제대로 설정할 수 있으므로 중요한 키워드임.

/**
 * Thrown when a suitable converter could not be found in a conversion service.
 *
 * @author Keith Donald
 * @since 3.0
 */
@SuppressWarnings("serial")
public final class ConverterNotFoundException extends ConversionException {

@param

파라미터 이름과 용도 기술

@return

description (return type and range of values)

@throws

exception-class descriptiom

{@code} Javadoc 에 예제 코드 작성

설명에 예제 코드를 첨부할 경우 {@code} 태그를 사용하면 되지만 이경우 개행이 되지 않으므로 HTML 의 <pre> 태그를 같이 사용해야 함.

/**
 * 클래스 설명: 예제
 * 
 * <pre>
 * {@code
 * Listener pl = new PieListener(kitchen);
 * int n = pl.forty();
 * }
 * </pre>
 */
public class JavadocTest {