Java Doc

JavaDoc 주석 다는 방법, 기본적인 예

여전이 주석이라는 것에 대해 긍정적인 면보다는 부정적인 면이 더 많다고 생각하고 있지만.. 소스 코드와 주석을 통해 멋지게 문서를 자동으로 생성해 주는 개념은 주석에 대한 부정적인 많은 부분을 불식시키고도 남는듯합니다.  Java로 만든 어플리케이션(또는 서비스)의 소스를 협업자 또는 제3자에게 제공하기 위해 주석을 달때 JavaDoc의 도움을 받아 좀더 체계적으로 작업할 수 있도록 하기 위한 주석법입니다. 간단히 제 스스로 개발할때 참고하여 사용할만한 예제 코드로 정리해 봅니다. 먼저 클래스에 대한 주석의 예입니다. view plaincopy to clipboardprint? /**   * 화면상에 윈도우를 나타내기 위한 클래스   * 사용 방법:   * <pre>   *    Window win = new Window(parent);   *    win.show();   * </pre>   *   * @author  Sami Shaio   * @version 1.0   * @see     java.awt.BaseWindow   * @see     java.awt.Button   */   class Window extends BaseWindow {      ...   }   다음은 클래스의 필드에 대한 주석의 예입니다. view plaincopy to clipboardprint?     /**       * 컴포넌트의 X 좌표       *       * @see #getLocation()       */       int x = 1263732;   끝으로 클래스의 매서드에 대한 주석의 예입니다. view plaincopy to clipboardprint?     /**       * 지정된 index에 위치하는 문자 반환.        * index의 범위는 <code>0</code>에서 <code>length() - 1</code>까지임.       *       * @param     index  얻고자 하는 문자의 인덱스 값       * @return      지정된 index의 문자       * @exception StringIndexOutOfRangeException       *     index가 <code>0</code>에서 <code>length()-1</code>의 범위를 벗어남       * @see       java.lang.Character#charValue()       */       public char charAt(int index) {          ...       }

자바에서 주석 처리는 3가지 형태가 있다.
// 와 /* */ 그리고 문서화 주석이라 하는 것

문서화 주석 는 /** 로 시작해서 */ 로 끝나는데 이문서화 주석를
사용하게 되면 javadoc 라는 유틸을 사용해 HTML 파일로 저장이 가능해 진다

즉 프로그램의 문서화를 편하게 할수 있는 것이다.

javadoc 에서 인식하는 태그는 아래와 같다.

@author 계발자
@deprecated 클래스나 멤버가 사장되었는지 지정
{@docRoot} 현 문서의 루트 디렉토리 경로 지정
@exception 메소드에서의 예외 확인
{@inhreitDoc} 상위 클래스로부터 주석을 상속
{@link} 다른 주제에 관한 인라인 링크 삽입
{@linkplain} 다른 주제에 관한 인라인 링크 삽입 - 링크가 평문 텍스트로 표시
@param 메소드의 매개변수 문서화
@return 메소드의 반환값 문서화
@see 다른 주제에 관한 링크 지정
@serial 기본 직렬화 필드 문서화
@serialData writeObject() 나 writeExteral() 메소드로 기록한 데이타 문서화 
@serialField ObjectStreamField 컴포넌트 문서화
@since 특별한 변경 사항이 소개될때 릴리즈 기록
@throws 메소드에서의 예외 확인
{@value} static 필드여야 하는 상수값 표시
@version 클래스의 버전

예)

/**

* 이 클래스는 .... 이다
* @author 아무개
* @version 1.1.2

*/