Javadoc 의 태그들

주석을 대충 살펴보면 아래와 같은 형태로 작성될 수 있을 것이다. 

package javax.servlet;
 
import java.util.EventListener;
 
/** 
 * Interface for receiving notification events about ServletContext
 * lifecycle changes.
 *
 * <p>In order to receive these notification events, the implementation
 * class must be either declared in the deployment descriptor of the web
 * application, annotated with {@link javax.servlet.annotation.WebListener},
 * or registered via one of the addListener methods defined on
 * {@link ServletContext}.
 *
 * <p>Implementations of this interface are invoked at their
 * {@link #contextInitialized} method in the order in which they have been
 * declared, and at their {@link #contextDestroyed} method in reverse
 * order.
 *
 * @see ServletContextEvent
 *
 * @since Servlet 2.3
 */
public interface ServletContextListener extends EventListener {
 
    /**
     * Receives notification that the web application initialization
     * process is starting.
     *
     * <p>All ServletContextListeners are notified of context
     * initialization before any filters or servlets in the web
     * application are initialized.
     *
     * @param sce the ServletContextEvent containing the ServletContext
     * that is being initialized
     */
    public void contextInitialized(ServletContextEvent sce);
 
    /**
     * Receives notification that the ServletContext is about to be
     * shut down.
     *
     * <p>All servlets and filters will have been destroyed before any
     * ServletContextListeners are notified of context
     * destruction.
     *
     * @param sce the ServletContextEvent containing the ServletContext
     * that is being destroyed
     */
    public void contextDestroyed(ServletContextEvent sce);
}

 

주석이 클래스에 대한 comment, 메소드에 대한 comment 로 구성된다고 보자.

주석 사이에 @로 시작되는 것들이 존재하는데 이것들을 tag라 부르는 것 같다.

 

주석을 작성할 때 아래와 같이 작성을 하면 javadoc으로 변환이 가능한 것 같다.

그렇지 않은 경우에는 변환이 되지 않는 모양이다.

/**

*/

이 주석사이에 @로 시작되는 태그들이 존재하고, 이 태그들은 어떤 것들이 있을까?

간략하게 태그종류만 살펴보고자 한다. 아직 처음 사용하는지라 명칭만 익숙해지고자 한다. 

 

 

@author

   - classes and interfaces only, required

   - 저자

 

@version

   - classes and interfaces only, required.

 

@param

   - (methods and constructors only)

   - 파라미터

 

@return (methods only)

   - return 

@exception

   - @throws is a synonym added in Javadoc 1.2

   - 예외

 

@see

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

   - 외부 링크를 걸어도 됨

@since

   - since 의 의미.

 

@serial (or @serialField or @serialData)

 

@deprecated (see How and When To Deprecate APIs)

  - 오래되어서 더이상 사용을 권장하지 않을 때.

 

사실 의미자체는 그렇게 어려운 느낌은 아니다.

다만 주석에 대한 근본 고민은 좀 있다. 어떻게 달아야 주석을 잘 달 수 있는가? 라는 것은 여전히 고민중이다.

그 과정중에 말이 너무 많지 않은 패턴으로 어떻게 형식화하면 좋을까에 대한 고민으로 Javadoc을 생각하게 되었다.

물론 다른 잡다한 이유도 좀 있지만.

 

몇 개의 예제를 살펴보자.

예제를 살펴보면 태그의 의미는 비교적 쉽게 이해가 되는 것 같다.

아래 예제는 전자정부표준프레임워크의 소스에서 가져왔다. 

 

/**
 *  Class Name : EgovProperties.java
 *  Description : properties값들을 파일로부터 읽어와   Globals클래스의 정적변수로 로드시켜주는 클래스로
 *   문자열 정보 기준으로 사용할 전역변수를 시스템 재시작으로 반영할 수 있도록 한다.
 *  Modification Information
 *
 *   수정일              수정자          수정내용
 *   ----------  --------  ---------------------------
 *   2009.01.19  박지욱          최초 생성
 *     2011.07.20    서준식        Globals파일의 상대경로를 읽은 메서드 추가
 *     2014.10.13    이기하        Globals.properties 값이 null일 경우 오류처리
 *   2019.04.26    신용호        RELATIVE_PATH_PREFIX Path 적용 방식 개선
 *  @author 공통 서비스 개발팀 박지욱
 *  @since 2009. 01. 19
 *  @version 1.0
 *  @see
 *
 */
 
public class EgovProperties {

/**
     * 첨부파일에 대한 목록 정보를 취득한다.
     *
     * @param files List<MultipartFile>
     * @param KeyStr String
     * @param fileKeyParam int
     * @param atchFileId String
     * @param storePath String
     * @returnList<FileVO>
     * @throws Exception Exception
     */
    public List<FileVO> parseFileInf(List<MultipartFile> files, String KeyStr, int fileKeyParam, String atchFileId, String storePath) throws Exception {