Javadoc 소개

1. 개요

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

다행히도 모든 최신 버전의 JDK는 소스 코드에있는 주석에서 API 문서를 생성하기위한 Javadoc 도구를 제공합니다.

전제 조건 :

  1. JDK 1.4 (최신 버전의 Maven Javadoc 플러그인에는 JDK 7 이상이 권장 됨)
  2. PATH 환경 변수에 추가 된 JDK / bin 폴더
  3. (선택 사항) 기본 제공 도구가있는 IDE

2. Javadoc 주석

주석부터 시작하겠습니다.

Javadoc 주석 구조는 일반 여러 줄 주석과 매우 유사 하지만 주요 차이점은 처음에 추가 별표가 있다는 것입니다.

// This is a single line comment /* * This is a regular multi-line comment */ /** * This is a Javadoc */

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

2.1. Javadoc 형식

Javadoc 주석은 문서화하려는 모든 클래스, 메소드 또는 필드 위에 놓일 수 있습니다.

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

  1. 우리가 주석을다는 것에 대한 설명
  2. 특정 메타 데이터를 설명 하는 독립형 블록 태그 ( " @ "기호로 표시됨)

이 예에서는 더 일반적인 블록 태그를 사용합니다. 전체 블록 태그 목록은 참조 가이드를 참조하세요.

2.2. 클래스 수준의 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 는 주석이 달린 클래스, 메서드 또는 필드를 추가 한 작성자의 이름입니다.

2.3. 필드 레벨의 Javadoc

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

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

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

2.4. 메소드 레벨의 Javadoc

메소드는 다양한 Javadoc 블록 태그를 포함 할 수 있습니다.

우리가 사용하고있는 방법을 살펴 보겠습니다.

/** * 

This is a simple description of the method. . . * Superman! *

* @param incomingDamage the amount of incoming damage * @return the amount of health hero has after attack * @see HERO-402 * @since 1.0 */ public int successfullyAttacked(int incomingDamage) { // do things return 0; }

successfullyAttacked 방법에 대한 설명과 수많은 독립 블록 태그를 모두 포함되어 있습니다.

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

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

  • @param 은 메소드의 매개 변수 또는 예상되는 입력에 대한 유용한 설명을 제공합니다.
  • @return 은 메소드가 반환하거나 반환 할 수있는 내용에 대한 설명을 제공합니다.
  • @see{@link} 태그 와 유사한 링크를 생성 하지만 인라인이 아닌 참조 컨텍스트에서 더 많이 생성됩니다.
  • @since specifies which version the class, field, or method was added to the project
  • @version specifies the version of the software, commonly used with %I% and %G% macros
  • @throws is used to further explain the cases the software would expect an exception
  • @deprecated gives an explanation of why code was deprecated, when it may have been deprecated, and what the alternatives are

Although both sections are technically optional, we'll need at least one for the Javadoc tool to generate anything meaningful.

3. Javadoc Generation

In order to generate our Javadoc pages, we'll want to take a look at the command line tool that ships with the JDK, and the Maven plugin.

3.1. Javadoc Command Line Tool

The Javadoc command line tool is very powerful but has some complexity attached to it.

Running the command javadoc without any options or parameters will result in an error and output parameters it expects.

We'll need to at least specify what package or class we want documentation to be generated for.

Let's open a command line and navigate to the project directory.

Assuming the classes are all in the src folder in the project directory:

[email protected]:~$ javadoc -d doc src\*

This will generate documentation in a directory called doc as specified with the –d flag. If multiple packages or files exist, we'd need to provide all of them.

Utilizing an IDE with the built-in functionality is, of course, easier and generally recommended.

3.2. Javadoc With Maven Plugin

We can also make use of the Maven Javadoc plugin:

   org.apache.maven.plugins maven-javadoc-plugin 3.0.0  1.8 1.8   ...    

In the base directory of the project, we run the command to generate our Javadocs to a directory in target\site:

[email protected]:~$ mvn javadoc:javadoc

The Maven plugin is very powerful and facilitates complex document generation seamlessly.

Let's now see what a generated Javadoc page looks like:

We can see a tree view of the classes our SuperHero class extends. We can see our description, fields, and method, and we can click on links for more information.

A detailed view of our method looks like this:

3.3. Custom Javadoc Tags

In addition to using predefined block tags to format our documentation, we can also create custom block tags.

In order to do so, we just need to include a -tag option to our Javadoc command line in the format of ::.

In order to create a custom tag called @location allowed anywhere, which is displayed in the “Notable Locations” header in our generated document, we need to run:

[email protected]:~$ javadoc -tag location:a:"Notable Locations:" -d doc src\*

In order to use this tag, we can add it to the block section of a Javadoc comment:

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

The Maven Javadoc plugin is flexible enough to also allow definitions of our custom tags in our pom.xml.

In order to set up the same tag above for our project, we can add the following to the section of our plugin:

...   location a Notable Places:   ...

This way allows us to specify the custom tag once, instead of specifying it every time.

4. Conclusion

이 빠른 소개 튜토리얼에서는 기본 Javadoc을 작성하고 Javadoc 명령 줄을 사용하여 생성하는 방법에 대해 설명했습니다.

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

항상 그렇듯이 코드 샘플은 GitHub에서 찾을 수 있습니다.