Javadoc

- Javadoc 이란?

좋은 API 문서는 소프트웨어 프로젝트 성공에 기여하는 여러 요소 중 하나이다.

- Javadoc 주석

/**
 *	This is 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

필드 수준의 Javadoc

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

javadoc으로 문서 생성시, 명시적으로 -private option을 추가한 경우에만 생성

메서드 수준의 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;
}

적절한 문서 생성을 위해 많은 블록 태그가 있으며 다양한 정보 포함
주석에서 기본 HTML 태그를 사용할 수도 있음

- Javadoc 생성

Javadoc 명령 줄 도구

javadoc -d doc src*

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>

프로젝트의 기본 디렉토리에서 다음 명령을 실행

mvn javadoc:javadoc

Javadoc을 target\site 디렉토리에 생성

사용자 정의 Javadoc 태그

생성된 문서에서 "Notable Locations" 헤더에 표시되는 위치에 @location이라는 사용자 정의 태그를 생성

Javadoc 명령에 -tag 옵션 포함

javadoc -tag location:a:"Notable Locations:" -d doc src*

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

- Maven 을 이용한 Javadoc 생성

site 에서 실행 후 프로젝트 폴더/target/site 디렉토리에 생성됨