elex/java-examples
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Files
09731f464d313c44cc4ae05651b97725ce146bc8
java-examples/docs/javadoc.md

9.6 KiB
Raw Blame History

자바독(Javadoc)은 자바 소스 코드에서 문서를 생성하기 위한 도구로, 주로 클래스, 인터페이스, 메서드, 필드 등에 대한 설명을 HTML 형식으로 생성합니다. Javadoc은 특정 태그(속성)를 사용하여 코드에 주석을 추가하며, 이를 기반으로 문서를 작성합니다. 아래에서는 Javadoc에서 지원하는 모든 속성(태그)을 표 형식으로 정리하고, 문서화를 잘하는 팁을 제공하겠습니다.

Javadoc에서 지원하는 속성(태그) 표

태그 설명 적용 대상
@author 코드 작성자를 지정 클래스, 인터페이스
@version 코드의 버전을 명시 클래스, 인터페이스
@since 해당 요소가 추가된 버전이나 날짜를 명시 모든 요소
@deprecated 해당 요소가 더 이상 권장되지 않음을 표시 (Java의 @Deprecated와 함께 사용 가능) 모든 요소
@see 관련 클래스, 메서드, 필드 등의 참조를 제공 모든 요소
@link 인라인 텍스트 내에서 다른 요소로의 하이퍼링크를 생성 모든 요소 (인라인)
@linkplain @link와 유사하지만, 링크 텍스트를 코드 스타일이 아닌 일반 텍스트로 표시 모든 요소 (인라인)
@param 메서드의 매개변수를 설명 메서드, 생성자
@return 메서드의 반환값을 설명 메서드
@throws / @exception 메서드가 던질 수 있는 예외를 설명 메서드, 생성자
@value 상수 필드의 값을 인라인으로 참조 필드 (static final)
@code 텍스트를 코드 스타일(모노스페이스)로 표시하며, HTML 태그를 이스케이프 처리 모든 요소 (인라인)
@literal 텍스트를 그대로 표시하며, HTML 태그를 이스케이프 처리 모든 요소 (인라인)
{@inheritDoc} 상위 클래스나 인터페이스의 Javadoc 설명을 상속 메서드, 클래스

각 태그 상세 설명 및 예시

1. @author

  • 설명: 코드 작성자를 나타냅니다. 여러 명일 경우 반복 사용 가능.
  • 예시:
/**
 * 사용자 관리 클래스
 * @author 홍길동
 * @author 김영희
 */
public class UserManager {}

2. @version

  • 설명: 코드의 버전을 명시합니다.
  • 예시:
/**
 * 계산기 유틸리티
 * @version 1.0.0
 */
public class Calculator {}

3. @since

  • 설명: 해당 요소가 추가된 시점을 기록합니다.
  • 예시:
/**
 * 사용자 ID 반환
 * @since 2023-01-01
 */
public Long getUserId() { return 1L; }

4. @deprecated

  • 설명: 더 이상 사용되지 않는 요소임을 알립니다.
  • 예시:
/**
 * 구형 메서드
 * @deprecated 대신 {@link #newMethod()}를 사용하세요.
 */
@Deprecated
public void oldMethod() {}

5. @see

  • 설명: 관련된 참조를 추가합니다.
  • 예시:
/**
 * 사용자 정보 클래스
 * @see java.util.List
 * @see UserManager#getUser()
 */
public class User {}

6. @link

  • 설명: 인라인 링크를 생성합니다.
  • 예시:
/**
 * 사용자를 추가합니다. 자세한 내용은 {@link UserManager}를 참조하세요.
 */
public void addUser() {}

7. @linkplain

  • 설명: @link와 비슷하지만 코드 스타일이 아닌 일반 텍스트로 표시.
  • 예시:
/**
 * 사용자를 삭제합니다. {@linkplain UserManager}에서 관리합니다.
 */
public void deleteUser() {}

8. @param

  • 설명: 메서드 매개변수를 설명합니다.
  • 예시:
/**
 * 두 수를 더합니다.
 * @param a 첫 번째 수
 * @param b 두 번째 수
 */
public int add(int a, int b) { return a + b; }

9. @return

  • 설명: 메서드 반환값을 설명합니다.
  • 예시:
/**
 * 사용자 이름을 반환합니다.
 * @return 사용자 이름 문자열
 */
public String getName() { return "홍길동"; }

10. @throws / @exception

  • 설명: 메서드가 발생시킬 수 있는 예외를 설명합니다 (동일한 기능).
  • 예시:
/**
 * 파일을 읽습니다.
 * @throws IOException 파일 읽기 실패 시 발생
 */
public void readFile() throws IOException {}

11. @value

  • 설명: 상수 필드의 값을 인라인으로 참조합니다.
  • 예시:
/**
 * 최대 사용자 수: {@value}
 */
public static final int MAX_USERS = 100;

12. @code

  • 설명: 코드 스타일로 텍스트를 표시하며, HTML 태그를 이스케이프합니다.
  • 예시:
/**
 * {@code null}을 반환할 수 있습니다.
 */
public String getValue() { return null; }

13. @literal

  • 설명: 텍스트를 그대로 표시하며, HTML 태그를 이스케이프합니다.
  • 예시:
/**
 * <b>중요</b>는 {@literal <b>중요</b>}로 표시됩니다.
 */
public void importantMethod() {}

14. {@inheritDoc}

  • 설명: 상위 클래스나 인터페이스의 Javadoc을 상속합니다.
  • 예시:
/**
 * {@inheritDoc}
 */
@Override
public String toString() { return super.toString(); }

문서화를 잘하는 팁

  1. 간결하고 명확하게 작성

    • 불필요한 장황함을 피하고 핵심 정보만 전달하세요.
    • 예: "이 메서드는 두 수를 더합니다." vs "두 정수를 더한 결과를 반환하는 함수입니다."

  2. 일관된 스타일 유지

    • 팀 내에서 Javadoc 스타일을 통일하세요 (예: 문장 끝에 마침표 사용 여부, 태그 순서 등).
    • 예: @param은 항상 먼저, @throws는 마지막에 배치.

  3. 의미 있는 설명 제공

    • 단순히 "이 메서드는 값을 반환합니다" 대신, 왜, 어떻게, 언제 사용되는지 설명하세요.
    • 예: 
      /**
 * 사용자 인증 토큰을 생성합니다. 
 * 로그인 성공 시 호출되며, 토큰은 24시간 유효합니다.
 * @param userId 사용자 ID
 * @return JWT 형식의 인증 토큰
 */

  4. 태그를 적절히 활용

    • 모든 메서드에 @param, @return, @throws를 빠뜨리지 말고 작성하세요.
    • @see와 @link로 관련 요소를 연결해 탐색성을 높이세요.

  5. 코드 예제 추가

    • 복잡한 메서드에는 사용 예제를 포함하세요.
    • 예: 
      /**
 * 문자열을 분리합니다.
 * 예: {@code splitString("a,b,c", ",")} -> ["a", "b", "c"]
 * @param input 입력 문자열
 * @param delimiter 구분자
 * @return 분리된 문자열 배열
 */

  6. Deprecated 요소 명확히 표시

    • @deprecated 태그와 함께 대체 방법을 제안하세요.
    • 예: 
      /**
 * @deprecated 대신 {@link #newMethod()}를 사용하세요.
 */

  7. HTML 태그 활용

    • <p>, <ul>, <li> 등을 사용해 가독성을 높이세요.
    • 예: 
      /**
 * <p>이 클래스는 사용자 정보를 관리합니다.</p>
 * <ul>
 *   <li>등록</li>
 *   <li>삭제</li>
 * </ul>
 */

  8. 프로젝트별 규칙 정의

    • @since, @author 등은 프로젝트 정책에 따라 선택적으로 사용하세요.
    • 예: 개인 프로젝트에서는 @author 생략 가능.

  9. 자동화 도구 활용

    • Maven이나 Gradle의 Javadoc 플러그인을 사용해 문서 생성을 자동화하세요.
    • 예 (Maven): 
      <plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <version>3.6.3</version>
    <executions>
        <execution>
            <goals>
                <goal>javadoc</goal>
            </goals>
        </execution>
    </executions>
</plugin>

  10. 정기적 리뷰

    • 코드 변경 시 Javadoc도 함께 업데이트하고, 팀 리뷰를 통해 누락된 부분을 점검하세요.

결론

Javadoc 태그는 자바 코드의 문서화를 체계적으로 지원하며, 잘 작성된 Javadoc은 코드의 유지보수성과 협업 효율성을 크게 높입니다. 위의 태그를 적절히 사용하고, 제공된 팁을 적용하면 읽기 쉽고 유용한 문서를 만들 수 있습니다. 프로젝트의 규모와 팀의 필요에 따라 문서화 수준을 조정하되, 최소한 핵심 요소(메서드 설명, 매개변수, 반환값, 예외)는 항상 포함하는 습관을 들이세요.

추가 질문이 있다면 언제든 물어보세요!

Reference in New Issue View Git Blame Copy Permalink