what is javadoc how use it generate documentation
이 자습서에서는 JavaDoc 도구 및 JavaDoc 주석 및 코드 문서 생성 방법에 대해 설명합니다.
JavaDoc은 JDK와 함께 패키지로 제공되는 특수 도구입니다. HTML 형식으로 Java 소스 코드의 코드 문서를 생성하는 데 사용됩니다.
Sun Microsystems (현재 Oracle Corporation)의 Java 언어에 대한 문서 생성기입니다.
학습 내용 :
JavaDoc이란?
이 도구는 '문서 주석'형식을 사용하여 Java 클래스를 문서화합니다. Eclipse, IntelliJIDEA 또는 NetBeans와 같은 IDE에는 HTML 문서를 생성하는 JavaDoc 도구가 내장되어 있습니다. 또한 프로그래머가 JavaDoc 소스를 생성하는 데 도움이되는 파일 편집기가 시장에 많이 나와 있습니다.
소스 코드 문서 외에도이 도구는 Java 애플리케이션의 구조를 분석하는 데 사용하는 'doclet'및 'taglet'을 생성하는 API도 제공합니다.
한 가지 주목할 점은 컴파일러가 Java 프로그램을 컴파일하는 동안 모든 주석을 제거하기 때문에이 도구는 어떤 식 으로든 응용 프로그램의 성능에 영향을주지 않는다는 것입니다.
프로그램에 주석을 작성한 다음 JavaDoc을 사용하여 문서를 생성하는 것은 프로그래머 / 사용자가 코드를 이해하는 데 도움이됩니다.
JavaDoc에서 생성 한 HTML 문서는 API 문서입니다. 선언을 구문 분석하고 소스 파일 세트를 생성합니다. 소스 파일은 필드, 메소드, 생성자 및 클래스를 설명합니다.
소스 코드에서 JavaDoc 도구를 사용하기 전에 프로그램에 특수 JavaDoc 주석을 포함해야합니다.
이제 댓글로 이동하겠습니다.
JavaDoc 주석
Java 언어는 다음 유형의 주석을 지원합니다.
# 1) 한 줄 주석 : 한 줄 주석은“ // ”및 컴파일러가 이러한 항목을 발견하면 줄 끝까지 이러한 주석 뒤에 오는 모든 내용을 무시합니다.
# 2) 여러 줄 주석 : 여러 줄 주석은“ /*….*/ ”. 따라서 '/ *'시퀀스를 만나면 컴파일러는 닫는 시퀀스 '* /'를 만날 때까지이 시퀀스 뒤에 오는 모든 것을 무시합니다.
# 3) 문서 주석 : 이를 문서 주석이라고하며 도구에서 API 문서를 생성하는 데 사용됩니다. 문서 주석은 ' / ** 문서 * / ”. 보시다시피 이러한 주석은 위에서 설명한 일반 주석과 다릅니다. 문서 주석에는 곧 보게 될 HTML 태그가 포함될 수도 있습니다.
diff 명령을 사용하여 두 파일을 비교하는 방법
따라서이 도구를 사용하여 API 문서를 생성하려면 프로그램에 이러한 문서 주석 (문서 주석)을 제공해야합니다.
JavaDoc 주석의 구조
Java의 Doc 주석 구조는 문서 주석의 여는 태그에 별표 (*)가 추가로 포함된다는 점을 제외하면 여러 줄 주석과 유사합니다. 따라서 문서 주석은‘/ *’대신‘/ **’로 시작합니다.
또한 JavaDoc 스타일 주석에는 HTML 태그가 포함될 수도 있습니다.
JavaDoc 주석 형식
문서화하려는 프로그래밍 구조를 기반으로 클래스, 메소드, 필드 등과 같은 구조 위에 문서 주석을 배치 할 수 있습니다. 각 구성의 문서 주석에 대한 예제를 살펴 보겠습니다.
수업 수준 형식
클래스 수준의 문서 주석 형식은 다음과 같습니다.
/** * Mechanic * * Please see the {@link sth.javadoctutes.Person} class for true identity * @author SoftwareTestingHelp * */ public class Mechanic extends Person { // fields and methods } 위에 표시된 것처럼 클래스 수준 문서 주석에는 클래스 작성자, 링크 (있는 경우) 등 모든 세부 정보가 포함됩니다.
방법 수준 형식
다음은 메서드 수준에서 문서 형식의 예입니다.
/** * simple method description … * JavaDoc! *
* @param msg the message to be printed * @return void * @see JavaDoc * @since 2.0 */ public void printMessage (String msg) { // do things return 0; } 위의 예에서 볼 수 있듯이 메서드의 문서 주석에 여러 태그를 가질 수 있습니다. 주석 설명 안에 단락이있을 수도 있습니다.
...
.반환 값 (@return)과 메서드의 매개 변수 (@param)를 설명하는 특수 태그도 있습니다.
필드 레벨 형식
다음 예제는 필드에 대한 문서 주석을 보여줍니다.
/** * The public name of a message */ private String msg_txt;위의 예에서 볼 수 있듯이 태그없이 평범한 주석을 가질 수도 있습니다. JavaDoc 명령으로 개인 옵션을 지정하지 않는 한 JavaDoc은 개인 필드에 대한 문서를 생성하지 않습니다.
이제 문서 주석과 함께 사용되는 태그에 대해 살펴 보겠습니다.
JavaDoc 태그
Java는 문서 주석에 포함 할 수있는 다양한 태그를 제공합니다. 이러한 태그를 사용할 때 도구는 이러한 태그를 구문 분석하여 소스 코드에서 올바른 형식의 API를 생성합니다.
각 태그는 대소 문자를 구분하며 '@'기호로 시작합니다. 위의 예에서 볼 수 있듯이 각 태그는 줄의 시작 부분에서 시작됩니다. 그렇지 않으면 컴파일러는이를 일반 텍스트로 처리합니다. 관례 적으로 동일한 태그가 함께 배치됩니다.
문서 주석에서 사용할 수있는 태그에는 두 가지 유형이 있습니다.
# 1) 블록 태그 : 블록 태그는 @tag_name .
블록 태그는 태그 섹션에 배치하고 주요 설명을 따를 수 있습니다. .
# 2) 인라인 태그 :인라인 태그는 중괄호로 묶여 있으며 다음과 같은 형식입니다. {@tag_name} . 인라인 태그는 문서 주석 내부에 배치 할 수 있습니다.
다음 표에는 문서 주석에서 사용할 수있는 모든 태그가 나열되어 있습니다.
| 꼬리표 | 기술 | 적용 |
|---|---|---|
| @return 설명 | 반환 값 설명을 제공합니다. | 방법 |
| @ 저자 xyz | 클래스, 인터페이스 또는 열거 형의 작성자를 나타냅니다. | 클래스, 인터페이스, 열거 형 |
| {@docRoot} | 이 태그에는 문서의 루트 디렉토리에 대한 상대 경로가 있습니다. | 클래스, 인터페이스, 열거 형, 필드, 메서드 |
| @ 버전 버전 | 소프트웨어 버전 항목을 지정합니다. | 클래스, 인터페이스, 열거 형 |
| @since 이후 텍스트 | 이 기능이 존재할 때부터 지정합니다. | 클래스, 인터페이스, 열거 형, 필드, 메서드 |
| @ 참조 참조 | 다른 문서에 대한 참조 (링크)를 지정합니다. | 클래스, 인터페이스, 열거 형, 필드, 메서드 |
| @param 이름 설명 | 메소드 매개 변수 / 인수를 설명하는 데 사용됩니다. | 방법 |
| @exception 클래스 이름 설명 | 메서드가 코드에서 throw 할 수있는 예외를 지정합니다. | 방법 |
| @throws 클래스 이름 설명 | ||
| @deprecated 설명 | 메서드가 오래된 것인지 지정합니다. | 클래스, 인터페이스, 열거 형, 필드, 메서드 |
| {@inheritDoc} | 상속의 경우 재정의 된 메서드에서 설명을 복사하는 데 사용됩니다. | 재정의 방법 |
| {@link 참조} | 다른 기호에 대한 참조 또는 링크를 제공합니다. | 클래스, 인터페이스, 열거 형, 필드, 메서드 |
| {@linkplain 참조} | {@link}와 동일하지만 일반 텍스트로 표시됩니다. | 클래스, 인터페이스, 열거 형, 필드, 메서드 |
| {@value #STATIC_FIELD} | 정적 필드의 값을 설명하십시오. | 정적 필드 |
| {@ 코드 리터럴} | {@literal}과 유사한 코드 글꼴로 리터럴 텍스트의 형식을 지정하는 데 사용됩니다.. | Class, Interface, Enum, Field, Method |
| {@literal literal} | Indicates literal text. the enclosed text is interpreted literally without any style formatting. | Class, Interface, Enum, Field, Method |
| {@serial literal} | Description of a serializable field. | Field |
| {@serialData literal} | Documents the data written by the writeExternal( ) or writeObject( ) methods. | Field, Method |
| {@serialField literal} | Describes an ObjectStreamField component. | Field |
Generate Java Doc
To create a JavaDoc you do not need to compile the Java file. We can generate JavaDoc documentation in two ways.
#1) Using JavaDoc Command Via Command Line
The command-line tool allows us to run the command through it.
This command can be executed on a command line and has the following syntax.
user@sth:~$javadoc –d doc src*
애니메이션을 온라인으로 볼 수있는 최고의 사이트
In the above command, we assume that all the files and Java classes are in the src folder. Also, the documentation will be generated in the specified ‘doc’ directory.
Note that running the “javadoc” command without any parameters or flags results in an error.
#2) Using The Tool From Any Of The Java IDEs.
All the major Java IDEs provide built-in functionality of generating documentation using the JavaDoc tool.
Using this built-in functionality is easier and also recommended than using a command-line tool to generate Java documentation.
Using JavaDoc With IntelliJIdea
Let’s generate documentation for a simple program using IntelliJIdea IDE.
We will consider the following program for which we have provided doc comments.
/** * Main class * * Please see the {@link www.softwaretestinghelp.com} class for true identity * @author SoftwareTestingHelp * */ public class Main{ /** * main method description … * JavaDoc! *
* @param args() string array * @return void * @see JavaDoc * */ public static void main(String args()) { System.out.println('Hello,World!!'); } } JavaDoc을 생성하기 위해 프로그램이나 프로젝트를 컴파일 할 필요가 없음을 알고 있습니다. IntelliJIdea Ide는 문서를 생성하는 내장 도구를 제공합니다. IntelliJIdea를 사용하여 문서를 생성하려면 아래 단계를 따르십시오.
- 도구-> JavaDoc 생성을 클릭하십시오.
- JavaDoc 도구를 클릭하면 다음 화면이 열립니다.
여기에서 전체 프로젝트에 대한 문서를 생성할지 아니면 하나의 클래스 만 생성할지 여부를 지정할 수 있습니다. 문서 파일이 생성 될 출력 디렉토리를 지정할 수도 있습니다. 위의 그림과 같이 다양한 사양이 있습니다.
모든 매개 변수가 지정되면 확인을 클릭하십시오.
- 이제 출력 창에서 Java Doc 생성 프로세스를 볼 수 있습니다. 샘플 Java Doc 출력 창은 다음과 같습니다.
- 생성이 완료되면 다음 파일이 생성됩니다.
- Main 클래스를 지정 했으므로 Main.html 파일이 생성됩니다. index.html도 Main.html과 동일한 내용을 가지고 있습니다.
- help-doc.html 파일에는 Java 엔티티의 일반 정의가 포함되어 있습니다. 이 파일의 내용 샘플은 다음과 같습니다.
- 마찬가지로 아래에 Main.html 파일의 샘플 콘텐츠가 있습니다.
따라서 이것이 IntelliJ 아이디어에서이 도구를 사용하여 문서를 생성 할 수있는 방법입니다. Eclipse 및 / 또는 NetBeans와 같은 다른 Java IDE에서 유사한 단계를 수행 할 수 있습니다.
자주 묻는 질문
Q # 1) JavaDoc의 용도는 무엇입니까?
대답: JavaDoc 도구는 JDK와 함께 제공됩니다. HTML 형식의 Java 소스 코드에 대한 코드 문서를 생성하는 데 사용됩니다. 이 도구를 사용하려면 소스 코드의 주석이 /**….*/로 미리 정의 된 형식으로 제공되어야합니다. 이를 문서 주석이라고도합니다.
Q # 2) Java 문서 예제는 무엇입니까?
대답: Java Doc 문서 도구는 웹 브라우저에서 문서를 볼 수 있도록 HTML 파일을 생성합니다. JavaDoc 설명서의 실제 예는 Oracle Corporation (http://download.oracle.com/javase/6/)의 Java 라이브러리 설명서입니다. 문서 /불/.
Q # 3) private 메서드에 JavaDoc이 필요합니까?
대답: 아니요. 비공개 필드와 방법은 개발자 전용입니다. 최종 사용자가 액세스 할 수없는 개인 메서드 또는 필드에 대한 문서를 제공하는 논리는 없습니다. Java Doc은 개인 엔티티에 대한 문서도 생성하지 않습니다.
Wi-Fi 비밀번호와 동일한 네트워크 보안 키입니다.
Q # 4) JavaDoc 명령이란 무엇입니까?
대답: 이 명령은 Java 소스 파일의 선언 및 문서 주석을 구문 분석하고 공용 및 보호 클래스, 중첩 클래스, 생성자, 메소드, 필드 및 인터페이스에 대한 문서를 포함하는 해당 HTML 문서 페이지를 생성합니다.
그러나 JavaDoc은 개인 엔티티 및 익명 내부 클래스에 대한 문서를 생성하지 않습니다.
결론
이 튜토리얼에서는 HTML 형식의 Java 소스 코드에 대한 코드 문서를 생성하는 데 유용한 JDK와 함께 패키지 된 JavaDoc 도구에 대해 설명했습니다. 명령 도구를 통해 Java Doc 명령을 실행하거나 대부분의 Java IDE에서 사용할 수있는 내장 JavaDoc 기능을 사용하여 문서를 생성 할 수 있습니다.
IntelliJIdea Java IDE와 함께 도구를 사용하여 문서를 생성하는 방법을 보았습니다. 이 튜토리얼은 또한 문서 주석과 함께 사용할 수있는 다양한 태그를 설명하여 도구가 소스 코드와 관련된 모든 정보를 자세히 설명하는 사용자 친화적 인 문서를 생성 할 수 있도록합니다.
=> 처음부터 Java를 배우려면 여기를 방문하십시오.
추천 도서
- Java 기초 : Java 구문, Java 클래스 및 핵심 Java 개념
- Java 배포 : Java JAR 파일 생성 및 실행
- Java Virtual Machine : JVM이 Java 응용 프로그램을 실행하는 데 도움이되는 방법
- 초보자를위한 JAVA 튜토리얼 : 100 개 이상의 실습 Java 비디오 튜토리얼
- Java 정수 및 Java BigInteger 클래스 (예제 포함)
- Java 구성 요소 : Java 플랫폼, JDK, JRE 및 Java Virtual Machine
- Postman에서 API 문서를 만드는 방법은 무엇입니까?