Java 문서 주석
Java에는 세 가지 주석 방법만 있습니다. 처음 두 개는 //와 /* */이고, 세 번째 유형은 /**다음으로 시작*/로 끝나는 설명 주석이라고 합니다.
설명 댓글을 사용하면 프로그램 내에 프로그램에 대한 정보를 삽입할 수 있습니다. javadoc 도구 소프트웨어를 사용하여 정보를 생성하고 이를 HTML 파일로 출력할 수 있습니다.
설명 댓글을 사용하면 프로그램에 대한 정보를 보다 포괄적으로 기록할 수 있습니다.
javadoc 태그
javadoc 도구 소프트웨어는 다음 태그를 인식합니다.
태그 | 설명 | 예 |
---|---|---|
@author | 수업 작성자 식별 | @작성자 설명 |
@deprecated | 만료된 수업 또는 구성원의 이름을 지정하세요. | @사용되지 않는 설명 |
{@docRoot} | 현재 문서 루트 디렉터리의 경로를 지정하세요 | 디렉터리 경로 |
@Exception | 수업에서 발생한 예외 표시 | @Exception 예외 이름 설명 |
{@inheritDoc} | 직계 상위 클래스에서 상속된 주석 | 직계 상위 클래스의 댓글을 상속받습니다. |
{@link} | 다른 주제에 대한 링크 삽입 | {@링크 이름 텍스트} |
{@linkplain} | 다른 주제에 대한 링크를 삽입하되 일반 텍스트 글꼴로 링크를 표시합니다. | 다른 주제에 대한 인라인 링크를 삽입합니다. |
@param | 메소드의 매개변수 설명 | @param 매개변수 이름 설명 |
@return | 반환 값 유형 설명 | @반환 설명 |
@see | 다른 주제에 대한 링크 지정 | @see 앵커 |
@serial | 직렬화 속성 설명 | @연재 설명 |
@serialData | writeObject() 및 writeExternal() 메서드를 통해 작성된 데이터 설명 | @serialData 설명 |
@serialField | ObjectStreamField 구성 요소 설명 | @serialField 이름 유형 설명 |
@since | 특정 변경 사항이 도입되면 표시하세요 | @출시 이후 |
@throws | @Exception 태그와 동일합니다. | @throws 태그는 @Exception 태그와 같은 의미를 갖습니다. |
{@value} | 정적 속성이어야 하는 상수 값을 표시합니다. | 정적 필드여야 하는 상수 값을 표시합니다. |
@version | 수업 버전 지정 | @version info |
Documentation comments
/**를 연 후 첫 번째 줄은 클래스, 변수, 메서드에 대한 주요 설명입니다.
그 뒤에는 하나 이상의 다양한 @를 포함할 수 있습니다. 태그. 각 @ 태그는 새 줄의 시작 부분에 있거나 줄 시작 부분에 바로 뒤에 별표(*)가 와야 합니다.
동일한 유형의 여러 태그는 함께 그룹화되어야 합니다. 예를 들어 @see 태그가 3개 있는 경우 하나씩 배치하세요.
다음은 클래스 설명 주석의 예입니다.
/*** This class draws a bar chart. * @author Zara Ali * @version 1.2 */
javadoc은 무엇을 출력합니까?
javadoc 도구는 Java 프로그램의 소스 코드를 입력으로 사용하고 프로그램에 대한 주석이 포함된 일부 HTML 파일을 출력합니다.
각 수업에 대한 정보는 별도의 HTML 파일에 저장됩니다. Javadoc은 상속된 트리 구조와 인덱스도 출력할 수 있습니다.
javadoc의 구현 방식이 다르기 때문에 작업 내용도 다를 수 있습니다. Java 개발 시스템의 버전과 기타 세부 사항을 확인하고 적절한 Javadoc 버전을 선택해야 합니다.
Example
다음은 Instruction Annotation을 활용한 간단한 예시입니다. 각 설명은 해당 설명이 설명하는 항목 앞에 옵니다.
javadoc 처리 후 SquareNum 클래스에 대한 주석은 SquareNum.html에서 찾을 수 있습니다.
import java.io.*; /** * This class demonstrates documentation comments. * @author Ayan Amhed * @version 1.2 */ public class SquareNum { /** * This method returns the square of num. * This is a multiline description. You can use * as many lines as you like. * @param num The value to be squared. * @return num squared. */ public double square(double num) { return num * num; } /** * This method inputs a number from the user. * @return The value input as a double. * @exception IOException On input error. * @see IOException */ public double getNumber() throws IOException { InputStreamReader isr = new InputStreamReader(System.in); BufferedReader inData = new BufferedReader(isr); String str; str = inData.readLine(); return (new Double(str)).doubleValue(); } /** * This method demonstrates square(). * @param args Unused. * @return Nothing. * @exception IOException On input error. * @see IOException */ public static void main(String args[]) throws IOException { SquareNum ob = new SquareNum(); double val; System.out.println("Enter value to be squared: "); val = ob.getNumber(); val = ob.square(val); System.out.println("Squared value is " + val); } }
다음과 같이 javadoc 도구를 사용하여 SquareNum.java 파일을 처리합니다.
$ javadoc SquareNum.java Loading source file SquareNum.java... Constructing Javadoc information... Standard Doclet version 1.5.0_13 Building tree for all the packages and classes... Generating SquareNum.html... SquareNum.java:39: 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... Generating stylesheet.css... 1 warning $