210310_B책_패키지를 JavaDoc으로 구조화하기

오늘은 3.7<패키지를 JavaDoc으로 구조화하기> 를 진행한다.
우선 JavaDoc이란 뭘까?

JavaDoc은 Java 코드에서 API 문서를 HTML 형식으로 생성해주는 도구입니다. HTML 형식이어서 관련 다른 API를 하이퍼 링크를 통해 접근이 가능하다는 장점이 있습니다.

라고 한다.
나도 실무에서 종종 본적있다.
API를 작성 중이고 API를 사용하는 데 다른 요소가 필요하다면 반드시 사용해야 한다고 한다.
우선 잘못된 예제 javadoc 사용을 보자면,

/**
 * logistics 라는 이 패키지는 물류를 위한 클래스를 포함한다.
 *
 * 이 패키지의 inventory 클래스는 화물선에 제품을 선적하고,
 * 변질된 제품은 모두 버릴 수 있다.
 * 이 패키지의 클래스:
 * - Inventory
 * - Supply
 * - Hull
 * - CargoShip
 * - SupplyCrate
 *
 * @author A. Lienm H. Uman
 * @version 1.8
 * @since 1.7
 * 
 */
 
package logistics;

javadoc을 한번도 사용해본적 없는 내 입장에서는 굉장히 깔끔하고
패키지를 분석하기 전에 본다면 매우 유용한 정보라고 생각한다.
클래스 목록도 나오고 어노테이션을 이용해 정보도 기술해 주었다.

하지만 요약문은 불필요하며 나머지 설명은 너무 추상적이라고 한다.
또한 마지막 표기도 전혀 유용하지 않다고 한다.

/**
 * 제품 재고를 관리하는 클래스
 *
 * **<p>**
 * 주요 클래스는 {@link logistics.Inventory} 로서 아래를 수행한다.
 * <ul>
 * <li> {@link logistics.CargoShip} 으로 선적하고, 
 * <li> 변질된 {@link logistics.Supply} 를 모두버리고,
 * <li> 이름으로 어떤 {@link logistics.Supply} 든 찾는다.
 * <ul>
 *
 * **<p>**
 * 이 클래스는 제품을 내리고 변질된 제품은 즉시 모두 버릴 수 있게 해준다.
 * <pre>
 * Inventory inventory = new Inventory();
 * Inventory.stockUp(cargoShip.unload());
 * Inventory.disposeContaminatedSupplies();
 * Inventory.getContaminatedSupplies().isEmpty(); // true
 * </pre>
 */
 
package logistics;

우선 영역 세 개를 수직으로 분리하고 불필요한 정보도 없앴다.
소개문은 패키지 내 클래스로 무엇을 할 수 있는지 매우 짧은 요약을 제공한다.
두 번째 부분은 패키지 내 주요 클래스로 무엇을 할 수 있는지 설명한다.
@link 표기를 사용함으로써 간단히 클래스를 클릭해 바로 이동할 수도 있다.

이러한 훌륭한 패키지 설명서는 이해도에 큰 변화를 불러온다.
패키지 내 모든 클래스로의 진입 장벽도 낮추기때문이다.

오늘의 코멘트: 나의 목표인 개찰구프로젝트를 구현할 때 써먹어야겠다 ㅋ_ㅋ