주석을 사용하기전에 기본적으로 앙ㄹ아야할 몇가지 개념들이 있다.
개념 부분은 지피티와 여러 블로그들을 ... . .짜깁기...
갑자기 왜 자바독을 쓰나??
과제 피드백으로 JAVADOC을 찾아보라고 했는데
자기가 만들었던 클래스들을 자동으로 정리해서 보여주는 기능이라고 한다.... 새롭게 알게되었으니 써먹어보려고 ㅎㅎ !!
📌 Javadoc이란?
Javadoc은 Java 코드에서 자동으로 문서를 생성하는 도구야.
즉, 주석을 활용해서 API 문서를 만들 수 있는 시스템이라고 보면 돼!
(💡 Java Development Kit(JDK)에 포함되어 있어!)
Java 소스 코드에서 HTML 형식의 API 문서를 생성하기 위해 Sun Microsystems에서 작성한 문서 생성기.
그러니깐 Javadoc은 일반 // 이런 주석이나 /* */ 이 주석이랑 다른 기능을 한다는 소리다
즉, Javadoc은 단순한 주석이 아니라 API 문서를 만들기 위한 주석이라고 한다.
목적 : 함수의 "사용법"과 "의도"를 설명
1. Javadoc으로 문서 생성하는 방법
1️⃣ 터미널(또는 명령 프롬프트)에서 Javadoc 실행하기
Javadoc을 실행하려면 Java 파일이 있는 디렉토리에서 다음 명령어를 입력한다..
javadoc -d docs Kiosk.java
🔹 -d docs : docs 폴더에 문서를 생성
사실 지금 생성은안된다.
왜냐하면 Javadoc으로 주석 안만들어줬으니간!!!!!!
난또 문서 먼저 만들고 자바 주석해놓으면 자동으로 추가되는건줄알았는데 반대인가봄
ㅎㅎ
2️⃣ 생성된 HTML 문서 확인
위 명령을 실행하면 docs 폴더 안에 .html 파일들이 생성되는데,
그중 index.html을 열어보면 Java API 문서처럼 정리된 문서를 볼 수 있어! 🔥
2. Javadoc의 기본 문법
📌Javadoc 주석은
/**로 시작해서*/로 끝나는 형태
/**
* 문서화 주석 내용
* 문서화 주석 내용
* 문서화 주석 내용
* 문서화 주석 내용
*/
아래의 형태도 똑같이 Javadoc의 대상이다.
/**
문서화 주석 내용
문서화 주석 내용
문서화 주석 내용
*/🏷️Javadoc 태그 종류
자바 버전이 올라가며 추가된 자바독 태그
{@literal} - 특수 문자를 그대로 출력
{@code} - 코드 블록을 강조
@implSpec - 메서드의 구현 세부 정보 설명
{@index} - 검색 인덱스 추가
문서화 주석 규칙들
다음은 문서화 주석의 규칙들이다.
- API를 올바르게 문서화하려면 모든 클래스, 인터페이스, 메서드, 필드 선언에 문서화 주석 달아야 한다.
- 직렬화 할 수 있는 클래스라면 직렬화 형태에 관해서도 적어야 한다.
- 문서화 주석이 없다면 Javadoc도 그저 공개 API 요소들의 '선언'만 나열해주는게 전부다.
- 문서화 주석 추가로 공개 API 요소들에 대한 설명을 클라이언트에게 명확하게 전달할 수 있다.
- 문서가 잘 갖춰지지 않은 API는 사용하기 헷갈릴 수 있어 오류의 원인이 되기 쉽다. (사용자에게 불편을 준다.)
- 기본 생성자에는 문서화 주석을 달 방법이 없으니 공개 클래스는 절대 기본 생성자를 사용하면 안된다.
(생성자를 따로 선언하지 않으면 기본 생성자를 사용한다.) - 상속용 클래스의 메서드는 문서화 애너테이션에 어떻게 동작해야 하는지를 기술한다.
- 상속용 클래스의 메서드가 아니라면 해당 메서드가 무엇인지를 기술한다.
- 메서드를 호출하기 위한 전제조건, 메서드가 성공적으로 수행된 후 만족해야하는 사후조건을 나열한다.
- 발생할 수 있는 부작용도 기술하자. 여기서 말하는 부작용이란 사후조건에 명확히 나타나지 않지만 시스템의 상태에 변화를 주는 것이다.
- 일반적으로 메서드의 제약조건은
@throws태그로 비검사 예외를 선언하여 기술한다. - 모든 매개변수에
@param태그 - 반환타입이
void가 아니라면@return태그 - 발생할 가능성이 있는 모든 예외에
@throws태그@throws태그의 설명은 '만약'으로 시작해 해당 예외를 던지는 조건을 설명하는 절이 뒤따른다.
@param, @return, @throws태그의 설명에는 마침표를 붙이지 않는다.{@code}는 감싼 내용을 코드용 폰트로 변환해주고, 다른 HTML 요소나 다른 자바독 태그를 무시한다.
단 @ 같은 경우는 탈출 문자를 써줘야 한다.
🍪 HTML 문법 사용이 가능!!
- 함수형 인터페이스 같이 어떻게 사용하는지 설명하는 게 중요한 경우는 예제나 ENUM 목록같이 보는사람이 편하게 텍스트를 구성할 필요가 있다.
3.적용시켜보자!!
일반 클래스
이런식으로 작성해봤다.
함수형 인터페이스
package challenge.lv2;
@FunctionalInterface
interface DiscountStructure {
int discountPrice(int price);
}
요게 함수형 인터페이스고
package challenge.lv2;
public enum DiscountType {
Coupon(price -> (price > 10000) ? price - 3000 : price),
Cash(price -> price - (price / 10)),
General(price -> price);
private final DiscountStructure discountStructure;
DiscountType(DiscountStructure discountStructure) {
this.discountStructure = discountStructure;
}
public int discountPrice(int price) {
return discountStructure.discountPrice(price);
}
}아래가 그것을 구현한 enum 클래스다
이런경우는 interface DiscountStructure 에서 이게 어디서 어떻게 사용되는지 적어주어야 한다고 한다.....
사실 작성하다가 말이좀 이상한건가..>? 싶은건 지선생한테 교정을 받았다 ㅋㅋㅋㅋ
이제 나머지도 적용해봐야징....
휴,,,다했다....
👊기본 생성자에는 문서화 주석을 달 방법이 없으니 공개 클래스는 절대 기본 생성자를 사용하면 안된다.
퍼블릭으로 선언해놓고 생성자가 없어서 문제가 생겼다 ㅋㅋㅋ
만들어주자..
4. 진짜로 Javadoc 문서 생성하기
특정 디렉토리에 안에들어간 모든 클래스에 대해 javadoc을만들어주기위해서 위오ㅏ같은 명령어를 입력했다.
인텔리제이 참 편하다
error가 없이 났다면 저거 실행한 위치에 docs디렉토리 생성된다.
이런식으로 내가 작성했던 javadoc 내용들이 html에 들어가서 나온다 우왕
5. 깃 허브에 올리고 리드미에 링크 첨부하기
깃 허브에 평범하게 자바독 내용들을 모두 올리고 나면 스크립트 형태로 보이게된다.
요것 지정해주면 링크처럼 볼 수있다!!
https://github.com/Ksr-ccb/Sparta-Kiosk
https://ksr-ccb.github.io/Sparta-Kiosk/challenge/lv2/package-summary.html
만들었던 자바 독 완성품이다!!!!! 깃허브 링클아 같이 올려야쥐
+++ private 함수도 javadoc에 표시해주기
javadoc -d docs -sourcepath src -subpackages challenge.lv2 -private
ㅠㅠㅠㅠㅠㅠ 열심히 작성한거 다 안올라가서 혼란혼란했다...
사실 지선생의 도움을 받아서 명령어 붙임...ㅎ
