자바 경험 치 포인트:클래스 주석 문서 작성 방법
자바 언어 에 있어 서 가장 자상 한 디자인 은 사람들 이 프로그램 을 쓰기 위해 프로그램 을 쓰 게 할 계획 이 없다 는 것 이다.사람들 도 프로그램의 문서 화 문 제 를 고려 해 야 한 다 는 것 이다.프로그램의 문서 화 에 있어 서 가장 큰 문 제 는 문서 유지 보수 입 니 다.문서 와 코드 가 분리 되면 코드 를 바 꿀 때마다 문 서 를 바 꾸 는 것 은 상당히 번 거 로 운 일이 될 것 이다.
해결 방법 은 매우 간단 해 보인다.코드 를 문서 와 연결 하 는 것 이다.이 를 위해 가장 쉬 운 방법 은 모든 내용 을 같은 파일 에 두 는 것 이다.그러나 모든 것 을 획일 적 으로 하기 위해 서 는 특수 한 문 서 를 표시 할 수 있 도록 특수 한 주석 문법 을 사용 해 야 한다.이 주석 들 을 추출 하고 가치 있 는 형식 으로 보 여 주 는 도구 도 필요 하 다.이것들 은 모두 자바 가 반드시 해 야 할 것 이다.
주석 을 추출 하 는 도 구 를 javadoc 라 고 합 니 다.그것 은 자바 컴 파일 러 에서 일부 기술 을 사용 하여 우리 가 프로그램 에 넣 은 특수 주석 표 시 를 찾 았 다.이 표 시 된 정 보 를 추출 할 뿐만 아니 라 주석 에 가 까 운 유형 이나 방법 명 도 추출 합 니 다.이렇게 되면 우 리 는 가장 가 벼 운 작업량 으로 매우 전문 적 인 프로그램 문 서 를 만 들 수 있다.
javadoc 출력 은 HTML 파일 로 웹 브 라 우 저 로 볼 수 있 습 니 다.이 도 구 는 하나의 원본 파일 을 만 들 고 관리 하 며 유용 한 문 서 를 생동감 있 게 만 들 수 있 습 니 다.jvadoc 가 있 기 때문에 우 리 는 표준 적 인 방법 으로 문 서 를 만 들 수 있 습 니 다.그리고 그것 이 매우 편리 하기 때문에 우 리 는 모든 자바 라 이브 러 리 의 문 서 를 쉽게 얻 을 수 있다.
2 구체 문법
모든 javadoc 명령 은"/*"주석 에 만 나타 날 수 있 습 니 다.그러나 평소 와 마찬가지 로 주석 은'*/'로 끝났다.주로 두 가지 방식 으로 javadoc:삽 입 된 HTML 을 사용 하거나'문서 태그'를 사용 합 니 다.문서 태그
tags)는'@'으로 시작 하 는 명령 으로 주석 줄 의 시작 부분 에 놓 여 있 습 니 다(그러나 선도 적 인'*'는 무시 합 니 다).
세 가지 유형의 주석 문서 가 있 는데 주석 뒤에 있 는 요소:클래스,변수 또는 방법 에 대응 합 니 다.즉,하나의 클래스 주석 은 하나의 클래스 정의 전에 있 습 니 다.변수 설명 은 변수 정의 전에 있 습 니 다.하나의 방법 정 의 는 하나의 방법 정의 앞 에 있다.아래 의 이 간단 한 예 에서 보 듯 이:
/**클래스 주석*/
public class docTest {
/*변수 설명*/
public int i;
/*한 가지 방법 설명*/
public void f() {}
}
javadoc 는 Public(공공)과 proctected(보 호 받 는)구성원 에 게 만 설명 문 서 를 처리 할 수 있 습 니 다."private'(개인)와'우호'(5 장 참조)멤버 들 의 설명 은 무시 되 고 출력 이 보이 지 않 습 니 다.(private 로 private 멤버 를 포함 하여 표시 할 수도 있 습 니 다.)이렇게 하 는 것 은 일리 가 있다.왜냐하면 Public 와 proctected 구성원 만 이 파일 밖에서 사용 할 수 있 기 때문에 이것 은 고객 프로그래머 의 희망 이다.그러나 모든 종류의 주석 은 출력 결과 에 포 함 됩 니 다.
상기 코드 의 출력 은 HTML 파일 로 다른 자바 문서 와 같은 표준 형식 을 가지 고 있 습 니 다.따라서 사용 자 는 이러한 형식 을 잘 알 고 디자인 의 유형 에서 편리 하 게'로 밍'할 수 있 습 니 다.프로그램 을 설계 할 때 상기 코드 를 입력 하고 자바 doc 로 처리 하여 최종 HTML 파일 의 효과 가 어떤 지 보 세 요.
3.HTML 삽입
javadoc 는 HTML 명령 을 최종 생 성 된 HTML 문서 에 전달 합 니 다.이것 은 우리 로 하여 금 HTML 의 거대 한 위력 을 충분히 이용 할 수 있 게 한다.물론 우리 의 최종 동 기 는 코드 를 포맷 하 는 것 이지 대중 에 게 영합 하기 위해 서가 아니다.다음 예 를 보 여 줍 니 다:
/**
*
* System.out.println(new Date());
*
*/
또한 다른 웹 문서 에서 처럼 HTML 을 사용 하여 일반 텍스트 를 포맷 하여 더욱 조리 있 고 아름 답 게 할 수 있 습 니 다.
/**
*목록 을 삽입 할 수도 있 습 니 다.
*
*
항목 1
*
프로젝트 2
*
프로젝트 3
*
*/
문서 주석 에서 한 줄 의 맨 끝 에 있 는 별 번 호 는 자바 doc 에 의 해 버 려 집 니 다.동시에 버 리 는 것 은 선도 빈 칸 도 있다.javadoc 는 모든 내용 을 포맷 하여 표준 문서 의 외관 과 일치 하도록 합 니 다.하지 마.
혹시
이러한 제목 은 HTML 삽입 으로 사 용 됩 니 다.javadoc 는 자신의 제목 을 삽입 하기 때문에 우리 가 제시 한 제목 은 충돌 합 니 다.
모든 종류의 주석 문서-클래스,변수 와 방법-HTML 삽입 을 지원 합 니 다.
4@see:다른 클래스 참조
모든 세 가지 유형의 주석 문 서 는@see 표 시 를 포함 할 수 있 습 니 다.다른 종류의 문 서 를 참조 할 수 있 습 니 다.이 태그 에 대해 javadoc 는 해당 HTML 을 생 성하 여 다른 문서 로 직접 연결 합 니 다.형식 은 다음 과 같 습 니 다.
@see 클래스
@see 전체 클래스 이름
@see 전체 클래스 이름
모든 형식 은 생 성 된 문서 에 하이퍼링크 의'See Also'(참조)항목 을 자동 으로 추가 합 니 다.javadoc 는 우리 가 지정 한 하이퍼링크 를 검사 하지 않 고 유효 하 는 지 검증 하지 않 습 니 다.
5 가지 문서 태그
HTML 과@see 참조 가 포함 되 어 있 으 며,클래스 문 서 는 버 전 정보 와 작성 자의 이름 에 대한 태그 도 포함 할 수 있 습 니 다.클래스 문 서 는'인터페이스'목적 에 도 사용 할 수 있 습 니 다.
1. @version
형식 은 다음 과 같 습 니 다.
@버 전 정보
그 중에서'버 전 정보'는 버 전 설명 에 적합 한 모든 자 료 를 대표 한다.javadoc 명령 행 에'-version'표 시 를 사용 하면 생 성 된 HTML 문서 에서 버 전 정 보 를 추출 합 니 다.
2. @author
형식 은 다음 과 같 습 니 다.
@author 작성 자 정보
그 중에서'작가 정보'는 귀하 의 성명,전자 우편 주소 또는 기타 적당 한 자 료 를 포함 합 니 다.javadoc 명령 행 에'author'표 시 를 사용 하면 생 성 된 HTML 문서 에서 작성 자 정 보 를 추출 합 니 다.
일련의 작 가 를 위해 여러 개의 표 시 를 사용 할 수 있 지만,그것들 은 반드시 연속 적 으로 배치 해 야 한다.모든 작성 자 정 보 는 최종 HTML 코드 의 단독 단락 에 함께 저 장 됩 니 다.
6 변수 문서 태그
변수 문 서 는 삽 입 된 HTML 과@see 참조 만 포함 할 수 있 습 니 다.
7 방법 문서 태그
HTML 과@see 인용 을 포함 하 는 것 외 에 방법 은 매개 변수,반환 값,규칙 에 어 긋 나 는 문서 표 시 를 사용 할 수 있 습 니 다.
1. @param
형식 은 다음 과 같 습 니 다.
@param 매개 변수 이름 설명
그 중에서'매개 변수 이름'은 매개 변수 목록 에 있 는 식별 자 를 말 하 는데'설명'은 후속 줄 에 이 어 질 수 있 는 설명 문 자 를 대표 한다.새 문서 표 시 를 만나면 이전 설명 이 끝났다 고 생각 합 니 다.임의의 수량의 설명 을 사용 할 수 있 습 니 다.매개 매개 변 수 는 하나 입 니 다.
2. @return
형식 은 다음 과 같 습 니 다.
@return 설명
그 중에서'설명'은 반환 값 의 의 미 를 가리킨다.그것 은 뒤의 줄 안 으로 이 어 질 수 있다.
3. @exception
'위반'(Exception)에 관 한 상세 한 상황 은 9 장 에서 설명 하 겠 습 니 다.쉽게 말 하면 그들 은 특수 한 대상 이다.만약 어떤 방법 이 실패 하면 그들 을'던 져'대상 으로 만 들 수 있다.하나의 방법 을 호출 할 때 비록 하나의 위반 대상 만 나타 나 지만 일부 특수 한 방법 은 임 의적 인 수량,서로 다른 유형의 위반 이 발생 할 수 있다.이 모든 위법 은 설명 이 필요 하 다.따라서 규정 에 위반 한 표지 의 형식 은 다음 과 같다.
@exception 전체 클래스 설명
그 중에서'완전한 유형 명'은 위반 류 의 이름 을 명확 하 게 지 정 했 는데 이것 은 다른 어 딘 가 에서 정 의 된 것 이다.그리고'설명'(똑 같이 아래 줄 로 이 어 질 수 있다)은 왜 이런 특수 한 유형의 위반 이 방법 호출 에서 나타 나 는 지 알려 준다.
4. @deprecated
이것 은 자바 1.1 의 새로운 특성 이다.이 표 시 는 일부 오래된 기능 이 개 선 된 새로운 기능 으로 대체 되 었 음 을 지적 하 는 데 쓰 인 다.이 태그 의 역할 은 사용자 가 특정한 기능 을 더 이상 사용 하지 않 아 도 된다 는 것 이다.왜냐하면 앞으로 개편 할 때 이 기능 을 버 릴 수 있 기 때문이다.하나의 방법 을@deprecated 로 표시 하면 이 방법 을 사용 할 때 컴 파일 러 의 경 고 를 받 을 수 있 습 니 다.
좋은 웹페이지 즐겨찾기
