Java - 문서 주석

Java 언어는 세 가지 유형의 주석을 지원합니다. -

Sr.No.	댓글 및 설명
1	/* 텍스트 */ 컴파일러는 /*에서 */까지 모든 것을 무시합니다.
2	//텍스트 컴파일러는 //부터 줄 끝까지 모든 것을 무시합니다.
3	/** 문서 */ 이것은 문서 주석이며 일반적으로 문서 주석이라고 합니다. . JDK javadoc 도구는 문서 주석을 사용합니다. 자동으로 생성된 문서를 준비할 때.

이 장은 Javadoc에 대한 모든 설명입니다. Javadoc을 사용하여 Java 코드에 대한 유용한 문서를 생성하는 방법을 살펴보겠습니다.

Javadoc이란 무엇입니까?

Javadoc은 JDK와 함께 제공되는 도구이며 사전 정의된 형식의 문서가 필요한 Java 소스 코드에서 HTML 형식의 Java 코드 문서를 생성하는 데 사용됩니다.

다음은 /*….*/ 안의 줄이 Java 여러 줄 주석인 간단한 예입니다. 마찬가지로 // 앞에 오는 줄은 Java 한 줄 주석입니다.

예시

/**
* The HelloWorld program implements an application that
* simply displays "Hello World!" to the standard output.
*
* @author  Zara Ali
* @version 1.0
* @since   2014-03-31 
*/
public class HelloWorld {

   public static void main(String[] args) {
      // Prints Hello, World! on standard output.
      System.out.println("Hello World!");
   }
}

설명 부분에 필수 HTML 태그를 포함할 수 있습니다. 예를 들어, 다음 예는 제목에

....

을 사용하고 단락 나누기를 만드는 데

를 사용했습니다 -

예시

/**
* <h1>Hello, World!</h1>
* The HelloWorld program implements an application that
* simply displays "Hello World!" to the standard output.
* <p>
* Giving proper comments in your program makes it more
* user friendly and it is assumed as a high quality code.
* 
*
* @author  Zara Ali
* @version 1.0
* @since   2014-03-31 
*/
public class HelloWorld {

   public static void main(String[] args) {
      // Prints Hello, World! on standard output.
      System.out.println("Hello World!");
   }
}

javadoc 태그

javadoc 도구는 다음 태그를 인식합니다 -

태그	설명	구문
@저자	클래스 작성자를 추가합니다.	@저자 이름-텍스트
{@code}	텍스트를 HTML 마크업이나 중첩된 javadoc 태그로 해석하지 않고 코드 글꼴로 텍스트를 표시합니다.	{@코드 텍스트}
{@docRoot}	생성된 페이지에서 생성된 문서의 루트 디렉토리에 대한 상대 경로를 나타냅니다.	{@docRoot}
@사용 중단	이 API가 더 이상 사용되지 않아야 함을 나타내는 주석을 추가합니다.	@deprecated deprecatedtext
@예외	던지기 추가 클래스 이름 및 설명 텍스트와 함께 생성된 문서의 부제목.	@예외 클래스 이름 설명
{@inheritDoc}	가장 가까운 주석을 상속합니다. 상속 가능한 클래스 또는 구현 가능한 인터페이스.	직접 슈퍼클래스에서 주석을 상속합니다.
{@link}	지정된 패키지, 클래스 또는 참조된 클래스의 멤버 이름에 대한 문서를 가리키는 보이는 텍스트 레이블이 있는 인라인 링크를 삽입합니다.	{@link package.class#member 레이블}
{@linkplain}	링크의 레이블이 코드 글꼴이 아닌 일반 텍스트로 표시된다는 점을 제외하면 {@link}와 동일합니다.	{@linkplain package.class#member 레이블}
@param	"매개변수" 섹션에 지정된 매개변수 이름 뒤에 지정된 설명이 오는 매개변수를 추가합니다.	@param 매개변수 이름 설명
@return	설명 텍스트와 함께 "반품" 섹션을 추가합니다.	@반환 설명
@see	참조를 가리키는 링크 또는 텍스트 항목과 함께 "참조 항목" 제목을 추가합니다.	@참조 참조
@serial	기본 직렬화 가능 필드에 대한 문서 주석에서 사용됩니다.	@serial 필드 설명 | 포함 | 제외
@serialData	writeObject( ) 또는 writeExternal( ) 메서드로 작성된 데이터를 문서화합니다.	@serialData 데이터 설명
@serialField	ObjectStreamField 구성 요소를 문서화합니다.	@serialField 필드 이름 필드 유형 필드 설명
@부터	생성된 문서에 지정된 이후 텍스트가 있는 "Since" 제목을 추가합니다.	@출시 이후
@throws	@throws 및 @exception 태그는 동의어입니다.	@throws 클래스 이름 설명
{@value}	정적 필드의 문서 주석에 {@value}를 사용하면 해당 상수의 값을 표시합니다.	{@value package.class#field}
@버전	-version 옵션이 사용될 때 생성된 문서에 지정된 버전 텍스트가 있는 "버전" 부제목을 추가합니다.	@버전 버전 텍스트

예

다음 프로그램은 문서 주석에 사용할 수 있는 몇 가지 중요한 태그를 사용합니다. 요구 사항에 따라 다른 태그를 사용할 수 있습니다.

AddNum 클래스에 대한 문서는 HTML 파일 AddNum.html에서 생성되지만 동시에 index.html이라는 이름의 마스터 파일도 생성됩니다.

import java.io.*;

/**
* <h1>Add Two Numbers!</h1>
* The AddNum program implements an application that
* simply adds two given integer numbers and Prints
* the output on the screen.
* <p>
* <b>Note:</b> Giving proper comments in your program makes it more
* user friendly and it is assumed as a high quality code.
*
* @author  Zara Ali
* @version 1.0
* @since   2014-03-31
*/
public class AddNum {
   /**
   * This method is used to add two integers. This is
   * a the simplest form of a class method, just to
   * show the usage of various javadoc Tags.
   * @param numA This is the first paramter to addNum method
   * @param numB  This is the second parameter to addNum method
   * @return int This returns sum of numA and numB.
   */
   public int addNum(int numA, int numB) {
      return numA + numB;
   }

   /**
   * This is the main method which makes use of addNum method.
   * @param args Unused.
   * @return Nothing.
   * @exception IOException On input error.
   * @see IOException
   */

   public static void main(String args[]) throws IOException {
      AddNum obj = new AddNum();
      int sum = obj.addNum(10, 20);

      System.out.println("Sum of 10 and 20 is :" + sum);
   }
}

이제 다음과 같이 javadoc 유틸리티를 사용하여 위의 AddNum.java 파일을 처리합니다. -

$ javadoc AddNum.java
Loading source file AddNum.java...
Constructing Javadoc information...
Standard Doclet version 1.7.0_51
Building tree for all the packages and classes...
Generating /AddNum.html...
AddNum.java:36: warning - @return tag cannot be used in method with void return type.
Generating /package-frame.html...
Generating /package-summary.html...
Generating /package-tree.html...
Generating /constant-values.html...
Building index for all the packages and classes...
Generating /overview-tree.html...
Generating /index-all.html...
Generating /deprecated-list.html...
Building index for all classes...
Generating /allclasses-frame.html...
Generating /allclasses-noframe.html...
Generating /index.html...
Generating /help-doc.html...
1 warning
$

여기에서 생성된 모든 문서를 확인할 수 있습니다 - AddNum. JDK 1.7을 사용하는 경우 javadoc은 훌륭한 stylesheet.css를 생성하지 않습니다. , 따라서 https://docs.oracle.com/javase/7/docs/api/stylesheet.css

에서 표준 스타일시트를 다운로드하여 사용하는 것이 좋습니다.