[JAVA] Javadoc란

main

 

좋은 API문서란 소프트웨어 프로젝트의 전반적인 성공에 기여하는 많은 요소들 중에 하나입니다.

JDK는 소스 코드에 있는 주석에서 API 문서를 생성하는 Javadoc 도구를 제공합니다.

Javadoc를 사용하기 필수 조건은 다음과 같습니다.

• (필수) JDK1.4 (Maven Javadoc 플러그인의 최신 버전에는 JDK7+을 권장함)
• (필수) PATH 환경 변수에 JDK/bin 폴더가 추가되어야 함
• (선택) 내장 도구가 있는 IDE

Javadoc 주석

Javadoc의 주석 구조는 일반적인 다중 줄 주석과 유사하지만 시작 부분에 별(*)이 하나더 추가되야 합니다.

// 한줄 주석입니다.

/*
 * 일반적인 여러줄 주석(멀티 주석) 입니다.
 */

/**
 * Javadoc 입니다.
 */

 

Javadoc 스타일 주석에는 HTML 태그도 포함될 수 있습니다.

Javadoc 형식

Javadoc 주석은 문서화하려는 클래스, 메서드 또는 필드 위에 배치할 수 있습니다.

이러한 주석은 일반적으로 두 섹션으로 구성됩니다.

• 우리가 논평하고 있는 내용에 대한 설명
• 특정 메타데이터를 설명하는 독립형 블록 태그("@"기호로 표시됨)

여기에서의 예제는 일반적인 블록 태그 중 일부를 사용할 예정입니다. 만약 블록 태그에 대한 전체적인 가이드는 여기를 참고하면 도움이 될 것입니다.

 

클래스 레벨의 Javadoc

클래스 수준의 Javadoc 주석에 대한 예입니다.

/**
* Hero is the main entity we'll be using to . . .
* 
* Please see the {@link com.baeldung.javadoc.Person} class for true identity
* @author Captain America
* 
*/
public class SuperHero extends Person {
    // fields and methods
}

 

위 예에서는 짧은 설명과 독립형과 인라인의 두 가지 다른 블록 태그를 가지고 있습니다.

• 독립형 태그는  설명 뒤에 나타나며 태그는 줄의 첫 번째 단어로 표시됩니다. (예: @author 태그)
• 인라인 태그는 어디에나 나타날 수 있으며 중괄호로 둘러싸야 합니다. (예: 설명의 @link 태그)

위 예에서 두 가지 종류의 블록 태그가 사용되는 것을 볼 수 있습니다.

• @link는 소스 코드의 참조된 부분에 대한 인라인 링크를 제공합니다.
• @author는 주석 처리된 클래스, 메서드 또는 필드를 추가한 작성자의 이름입니다.

필드 레벨의 Javadoc

SuperHero 클래스 내부에서 이와 같이 블록 태그 없이 설명을 사용할 수도 있습니다.

/**
 * The public name of a hero that is common knowledge
 */
private String heroName;

 

- private 옵션을 Javadoc 명령에 명시적으로 전달하지 않는 한 비공개 필드에는 Javadoc이 생성되지 않습니다.

메서드 수준의 Javadoc

메서드에 대한 다양한 Javadoc 블록 태그가 포함될 수 있습니다.

/**
 * <p>This is a simple description of the method. . .
 * <a href="http://www.supermanisthegreatest.com">Superman!</a>
 * </p>
 * @param incomingDamage the amount of incoming damage
 * @return the amount of health hero has after attack
 * @see <a href="http://www.link_to_jira/HERO-402">HERO-402</a>
 * @since 1.0
 */
public int successfullyAttacked(int incomingDamage) {
    // do things
    return 0;
}

 

successfulAttacked 메서드에는 설명과 여러 개의 독립적인 블록 태그가 포함되어 있습니다.

적절한 문서를 생성하는데 도움이 되는 많은 블록 태그가 있으며, 모든 종류의 다양한 정보를 포함할 수 있습니다.

위의 예에서 사용한 태그를 살펴보겠습니다.

• @param은 메서드의 매개변수 또는 예상해야 하는 입력에 대한 유용한 설명을 제공합니다.
• @return은 메서드가 반환하거나 반환할 수 있는 내용에 대한 설명을 제공합니다.
• @see는 @link 태그와 유사한 링크를 생성 하지만 참조 컨텍스트에 더 가깝고 인라인이 아닙니다.
• @since는 프로젝트에 추가된 클래스, 필드 또는 메서드의 버전을 ㅣ정합니다.
• @version은 %I% 및 %G% 매크로와 함께 일반적으로 사용되는 소프트웨어 버전을 지정합니다.
• @throws는 소프트웨어가 예외를 예상하는 경우를 추가로 설명하는데 사용됩니다.
• @deprecated는 더이상 사용되지 않는 이유, 더 이상 사용되지 않는 경우 및 대안에 대한 설명을 제공합니다.

두 섹션 모두 기술적으로 선택 사항이기는 하지만 Javadoc 도구에서 의미 있는 내용을 생성하려면 적어도 하나는 필요합니다.

Javadoc 생성

Javadoc 페이지를 생성하기 위해서는 JDK 및 Maven 플러그인과 함께 제공되는 명령줄 도구를 살펴보겠습니다.

Javadoc 명령줄 도구

Javadoc 명령줄 도구는 매우 강력하지만, 다소 복잡합니다.

옵션이나 매개변수 없이 javadoc 명령을 실행하면 오류가 발생하고, 예상하는 매개변수가 출력됩니다.

최소한 어떤 패키지나 클래스에 대한 문서를 생성할지 지정해야 합니다.

명령줄을 열고 프로젝트 디렉토리로 이동하여 모든 클래스가 프로젝 디렉토리의 src 폴더에 있다고 가정해 봅시다.

user@baeldung:~$ javadoc -d doc src\*

 

이렇게 하면 -d 플래그로 지정된 대로 doc이라는 디렉토리에 문서가 생성됩니다. 열 ㅓ패키지나 파일이 있는 경우 모두 제공해야 합니다.

물론, 내장된 기능이 있는 IDE를 활용하는 것이 더 쉽고 일반적으로 권장됩니다.

Maven 플러그인을 사용한 Javadoc

Maven Javadoc 플러그인을 활용할 수도 있습니다.

 

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-javadoc-plugin</artifactId>
            <version>3.6.2</version>
            <configuration>
                <source>1.8</source>
                <target>1.8</target>
            </configuration>
            <tags>
            ...
            </tags>
        </plugin>
    </plugins>
</build>

 

프로젝트으 ㅣ기본 디렉토리에서 target/site의 디렉토리에 Javadoc을 생성하는 명령을 실행합니다.

user@baeldung:~$ mvn javadoc:javadoc

 

Maven 플러그인은 매우 강력하며 복잡한 문서 생성을 원활하게 해줍니다.

이젠 생성된 Javadoc 페이지가 어떻게 생겼는지 살펴보겠습니다.

생성된 javadoc

SuperHero 클래스가 확장하는 클래스의 트리 뷰를 볼 수 있습니다. 설명, 필드, 메서드를 볼 수 있으며, 링크를 클릭하면 자세한 정보를 볼 수 있습니다.

자세히 살펴보면 다음과 같습니다.

자세한 정보

사용자 정의 Javadoc 태그

사전 정의된 블록 태그를 사용하여 문서를 포멧하는 것 외에도 사용자 정의 블록 태그를 만들 수도 있습니다. <tag-name>:<locations-allowed>:<header>형식으로 Javadoc 명령줄에 -tag 옵션을 포함하기만 하면 됩니다.

생성된 문서의 "주요 위치"헤더에 표시되는 @location allowed anywhere라는 사용자 정의 태그를 생성하려면 다음을 실행해야합니다.

user@baeldung:~$ javadoc -tag location:a:"Notable Locations:" -d doc src\*

 

그런 다음 이 태그를 사용하려면 javadoc 주석의 블록 섹션에 태그를 추가하면 되빈다.

/**
 * This is an example...
 * @location New York
 * @returns blah blah
 */

 

Maven Javaodc 플러그인 pom.xml에서 사용자 정의 태그를 정의할 수 있을 만큼 유연합니다.

프로젝트에 위와 같은 태그를 설정하기 위해 프롤그인의 <tags> 섹션에 다음을 추가할 수 있습니다.

...
<tags>
    <tag>
        <name>location</name>
        <placement>a</placement>
        <head>Notable Places:</head>
    </tag> 
</tags>
...

 

이 방법은 사용하면 사용자 정의 태그를 매번 지정하지 않고도 한번 지정할 수 있습니다.

 

 

 

문서를 생성하는 더 쉬운 방법은 IDE 옵션을 사용거나 Maven 플러그인을 pom.xml 파일에 포함하고 적절한 명령을 실행하는 것입니다.

 

 

 

 

 

gradle 플러그인 및 IDE(eclipse, intellij)에서 되는지 아시는 분이 있다면 공유 부탁드립니다.

 

 

 

 

 

 

 

 

 

 

 

 

출처: https://www.baeldung.com/javadoc