Javadoc 사용하기

JavaDoc이란 무엇인가?

JavaDoc은 Java 코드에서 API 문서를 HTML 형식으로 생성해주는 도구입니다. HTML 형식이어서 관련 다른 API를 하이퍼 링크를 통해 접근이 가능하다는 장점이 있습니다.

Android 개발자라면 Android 개발자 사이트에서 자주 보았을 형식이며, 소스코드에 약간의 annotation만 추가하면 멋진 문서형식으로 정리되기 때문에 사용하는 습관을 들이길 권장합니다!

(Android는 당연하고 Kakao SDK(Link)에서도 .css파일만 변경하여 JavaDoc으로 가이드 문서를 제공하고 있는 듯 합니다.)

JavaDoc Tags

JavaDoc은 여러 Tag를 작성하여 문서를 완성합니다.

Tag는 Java 소스코드에 annotation(주석)으로 추가하며, Android Studio에서 ‘/**’ 까지 입력 후 Enter를 치면 자동으로 기본 형식이 추가됩니다.

Javadoc Tags 종류는 다음과 같습니다.

@author
@deprecated
@exception
@param
@return
@see
@serial
@serialData
@serialField
@since
@throws
@version

아래 내용은 위 태그를 직접 만든 Gallery Project(Link)에 적용한 예제입니다.

Class 또는 Interface

/**
 * A class is the Manager that gets the album and photo list of the device.
 * For example:
 * <pre>
 *     GalleryManager manager = new GalleryManager(context, listener);
 *     galleryManager.getImageAlbums();
 *     galleryManager.getImagePhotos(album);
 * </pre>
 *
 * @author ejiaah
 * @version 1.0.0 19/03/13
 * @see com.ejiaah.gallery.Photo
 * @see com.ejiaah.gallery.Album
 */
class GalleryManager {
   ...
}

/**
 * A Listener receives Album/Photo list asynchronously.
 */
public interface GalleryListener {
    ...
}

alt

Field

/**
 * Name of Album
 *
 * @see #getName()
 * @see #setName(String)
 */
private String name = "";

/**
 * Number of photos in Album
 *
 * @see #getCount()
 * @see #setCount(int)
 */
private int count = 0;

alt alt

Constructor and Method Tags

/**
 * Get a list of photos from the Album.
 *
 * @param album
 * @since 1.0.0
 */
public void getImagePhotos(final Album album) {
    ...
}

/**
 * Test method. 테스트 함수
 *
 * @param stringNumber
 * @return isNumberForamt
 * @throws NullPointerException parameter is null or empty
 *
 * @since 1.0.0
 * @deprecated 1.0.1
 */
public boolean isNumberFormat(String stringNumber) {
    if(TextUtils.isEmpty(stringNumber)) {
        throw new NullPointerException();
    }

    try {
        int number = Integer.parseInt(stringNumber);
    } catch (NumberFormatException e) {
        e.printStackTrace();
        return false;
    }
    return true;
}

alt alt