[Java] JavaDoc

JavaDoc이란 제품 설명서와 같은 의미인데요.

가전 제품을 살 때 안에 있는 설명서라고 생각하면 됩니다.

우리가 만든 프로그램을 보기 쉽게 HTML형식,

WEB형식으로 만들어서 문서화 시킨것을 의미합니다.

JavaDoc은 만들 때 주석을 달게 됩니다.

주석은 /**   내용   */ 이런식으로

별 2개짜리 주석을 달게 됩니다.

주석은 2개의 영역으로 나뉘는데

먼저 설명문이 있습니다.

설명문은 주석의 시작에서 첫번째 태그 섹션까지의 부분을 의미합니다.

HTML로 설명되기 때문에 단순히 주석 작성 당시에 엔터를 쳐서 줄을 바꿔서

입력했더라도 그대로 이어져서 출력하게 됩니다.

줄바꿈 처리를 하고 싶다면 <p>를 작성하면 됩니다.

두번째는 태그 섹션입니다.

첫번째 문자가 @로 시작하고 아래와 같은 형식인데

- @author : 이 프로그램의 작성자

△ 기본값으로 Windows 계정 ID가 들어있습니다.

- @version : 말 그대로 이 프로그램의 버전

- @param : 파라미터에 대한 설명을 할 때 사용

- @throws : 예외처리에 대한 설명

- @return : 메소드에 void가 아닌 반환 값이 있을 때 그것에 대한 설명

등이 있습니다.

 

예시로 한 번 작성해볼까요?

 

/**

* 게임 캐릭터의 정보를 가지고 있는 클래스

* <p>

* @author puft

* @version 1.1.14

*/

전체 클래스에 대한 태그섹션입니다.

 

public Character(String name)throws IllegalAccessException {

level = 1;

job = "초보자";

equipment = "목검";

nickname = name;

if(nickname.length() < 3 || nickname.length() > 10) {

throw new IllegalAccessException("캐릭터의 이름은 3자 이상 10자 이하입니다.");

}

}

 

이런 식으로 캐릭터 생성자가 있을 때

 /**

* 게임 캐릭터를 생성합니다.

* <p> 기본 레벨은 1, 기본 직업은 초보자, 기본 무기는 목검입니다.

* @param name 캐릭터의 이름; 길이는 3자 이상 10자 이하이어야 합니다.

* @throws IllegalAccessException 캐릭터의 nickname의 길이가

* 정해진 범위를 벗어나면, 즉({@code nickname < 3 || nickname > 10}) 이면 발생합니다.

*

*/

 태그 섹션을 작성할 수 있습니다.

작성한 뒤 main을 실행하고

 

project도구의 Generate Javadoc을 누릅니다.

tag 리스트들을 확인 후 next를 누릅니다.

 

 

그리고 finish이전 탭에서

-locale ko_KR -encoding UTF-8 -charset UTF-8 -docencoding UTF-8

위와 같이 encoding에러 방지 코드를 적어줍니다.

모든 코드를 UTF-8 방식으로 바꾸는 코드입니다.

 

Loading source file C:\Users\sdedu\Desktop\실습코드\javaex\Dec11_1_OOP_Static\src\OMain1.java...

Constructing Javadoc information...

Standard Doclet version 1.8.0_332

Building tree for all the packages and classes...

Generating C:\Users\sdedu\Desktop\OMain1.html...

Generating C:\Users\sdedu\Desktop\package-frame.html...

Generating C:\Users\sdedu\Desktop\package-summary.html...

Generating C:\Users\sdedu\Desktop\package-tree.html...

Generating C:\Users\sdedu\Desktop\constant-values.html...

Generating C:\Users\sdedu\Desktop\class-use\OMain1.html...

Generating C:\Users\sdedu\Desktop\package-use.html...

Building index for all the packages and classes...

Generating C:\Users\sdedu\Desktop\overview-tree.html...

Generating C:\Users\sdedu\Desktop\index-files\index-1.html...

Generating C:\Users\sdedu\Desktop\index-files\index-2.html...

Generating C:\Users\sdedu\Desktop\deprecated-list.html...

Building index for all classes...

Generating C:\Users\sdedu\Desktop\allclasses-frame.html...

Generating C:\Users\sdedu\Desktop\allclasses-noframe.html...

Generating C:\Users\sdedu\Desktop\index.html...

Generating C:\Users\sdedu\Desktop\help-doc.html...

 

이런 식으로 출력되면 파일이 잘 생성된 겁니다.

해당 클래스의 파일을 실행해보면

Document

 

이렇게 Document페이지에 접속할 수 있습니다.

 

이번 시간에는 JavaDoc에 대해서 배워봤는데요.

프로그램 개발을 구현하는게 끝이 아닌

문서화 작업을 통해서 사용자에게 기능에 대한

설명을 제시할 수 있도록 잘 정리하는 것도

좋은 프로그래머가 되는 길 중 하나라고 생각이 드는 시간이었던 것 같습니다.