매일 Thinking in java:6 주석 과 문서 삽입

주석 과 문서 삽입(Comments and embedded documentation)
자바 에는 두 가지 종류의 주석 이 있다.첫 번 째 는 전통 적 이 고 C 언어 스타일 의 주석 으로 C++에서 계승 되 었 다.주석 은 하나“/*”로 시작 하고 그 다음 에 주석 내용 이 며 여러 줄 을 뛰 어 넘 을 수 있 으 며 마지막 에 하나“*/”로 끝난다.

/*   
*     ，
*        
*/

그러나 컴 파일 을 진행 할 때/* */사이 의 모든 것 이 무시 된다 는 것 을 기억 하 십시오.따라서 상기 주석 은 아래 의 주석 과 다 르 지 않 습 니 다.

/*       ，
        */

두 번 째 유형의 주석 도 C++에서 기원 되 었 다.이 주석 은'한 줄 주석'이 라 고 하 는데'/'로 시작 하여 이 줄 의 모든 내용 이 주석 임 을 나타 낸다.이런 유형의 주석 은 글 을 쓸 때 더욱 편리 하기 때문에 더욱 자주 사용 된다.키보드 에서'/'를 찾 을 필요 가 없고'*'(같은 키 를 두 번 누 르 면)를 찾 을 필요 가 없 으 며 주석 끝 에 끝 표 시 를 추가 할 필요 가 없습니다.다음은 이러한 주석 의 예 입 니 다.

//         

주석 문 서 는 주석 을 추출 하 는 데 사용 되 는 도 구 를 자바 doc 라 고 합 니 다.그것 은 자바 컴 파일 러 에서 일부 기술 을 사용 하여 우리 가 프로그램 에 넣 은 특수 주석 표 시 를 찾 았 다.이 표 시 된 정 보 를 추출 할 뿐만 아니 라 주석 에 가 까 운 유형 이나 방법 명 도 추출 합 니 다.이렇게 되면 우 리 는 가장 가 벼 운 작업량 으로 매우 전문 적 인 프로그램 문 서 를 만 들 수 있다.javadoc 출력 은 HTML 파일 로 웹 브 라 우 저 로 볼 수 있 습 니 다.이 도 구 는 하나의 원본 파일 을 만 들 고 관리 하 며 유용 한 문 서 를 생동감 있 게 만 들 수 있 습 니 다.
모든 javadoc 명령 은"/*"주석 에 만 나타 날 수 있 으 며,주석 은"*/"로 끝 납 니 다.javadoc 를 사용 하 는 두 가지 방법 이 있 습 니 다.

HTML 삽입,

'문서 태그'(Doc tags)를 사용 합 니 다.문서 표 시 는'@'으로 시작 하 는 명령 으로 주석 줄 의 시작 부분 에 두 지만 선도 적 인'*'는 무시 합 니 다.

세 가지 유형의 주석 문서 가 있 는데 주석 뒤에 있 는 요소:클래스,변수 또는 방법 에 대응 합 니 다.클래스 설명 은 클래스 정의 전에;변수 설명 은 변수 정의 전에;방법 설명 은 방법 정의 앞 에 있 습 니 다.
다음 과 같은 예 에서 보 듯 이:

/**       */
public class docTest {
/**        */
public int i;
/**        */
public void f() {}
}

javadoc 는 Public(공공)과 proctected(보 호 받 는)구성원 에 게 만 설명 문 서 를 처리 할 수 있 습 니 다."private'(개인)와'우호'(5 장 참조)멤버 들 의 설명 은 무시 되 고 출력 이 보이 지 않 습 니 다.(private 로 private 멤버 를 포함 하여 표시 할 수도 있 습 니 다.)퍼 블 릭 과 proctected 멤버 만 파일 밖에서 사용 할 수 있 기 때문이다.모든 종류의 주석 은 출력 결과 에 포 함 됩 니 다.
HTML javadoc 를 삽입 하여 HTML 명령 을 최종 생 성 된 HTML 문서 에 전달 합 니 다.이것 은 HTML 을 충분히 이용 할 수 있다.이렇게 하 는 최종 목적 은 역시 포맷 코드 이다.다음 예 참조:

/**
* 

* System.out.println(new Date());
* 
*/
웹 문서 에서 HTML 을 사용 하 는 것 처럼 일반 텍스트 를 포맷 하여 더욱 조리 있 고 아름 답 게 할 수도 있 습 니 다.
/**
*            ：
* 

* 
    
* 
    
* 
    
* 
*/
  
문서 주석 에서 줄 마다 맨 처음 별표 가 javadoc 에서 무 시 됩 니 다.전방 스페이스 바(leading spaces)도 무시 합 니 다.javadoc 는 모든 내용 을 포맷 하여 표준 문서 의 외관 과 일치 하도록 합 니 다. 
와 같은 제목 을 HTML 에 삽입 하 는 것 으로 사용 하지 마 십시오.javadoc 는 자신의 제목 을 삽입 하기 때 문 입 니 다.모든 종류의 주석 문서 인 클래스,변수,방법 은 HTML 삽입 을 지원 합 니 다.
@see:다른 세 가지 유형의 주석 문 서 를 참조 하면@see 표 시 를 포함 할 수 있 습 니 다.다른 종류의 문 서 를 참조 할 수 있 습 니 다.이 태그 에 대해 javadoc 는 해당 HTML 을 생 성하 여 다른 문서 로 직접 연결 합 니 다.형식 은 다음 과 같 습 니 다.
@see 클래스 이름@see 전체 클래스 이름@see 전체 클래스 이름\#방법 이름
모든 형식 은 생 성 된 문서 에 하이퍼링크 의'See Also'(참조)항목 을 자동 으로 추가 합 니 다.javadoc 는 우리 가 지정 한 하이퍼링크 를 검사 하지 않 고 유효 하 는 지 검증 하지 않 습 니 다.
클래스 문서 표 시 는 HTML 과@see 참조 가 포함 되 어 있 으 며,클래스 문 서 는 버 전 정보 와 작성 자의 이름 에 대한 표 시 를 포함 할 수 있 습 니 다.클래스 문 서 는 인터페이스 에 도 사용 할 수 있 습 니 다.
@version 형식 은 다음 과 같 습 니 다.@version 버 전 정보 에서'버 전 정보'는 버 전 설명 에 적합 한 모든 자 료 를 대표 합 니 다.javadoc 명령 행 에서"-version"표 시 를 사용 하면 생 성 된 HTML 문서 에서 버 전 정 보 를 추출 합 니 다.
  
@author 형식 은 다음 과 같 습 니 다.@author 작가 의 정보 중'작가 정보'는 이름,전자 우편 주소 또는 기타 적합 한 자 료 를 포함 합 니 다.javadoc 명령 행 에"-author"표 시 를 사용 하면 생 성 된 HTML 문서 에서 작성 자 정 보 를 추출 합 니 다.일련의 작 가 를 위해 여러 개의 표 시 를 사용 할 수 있 지만,이것들 은 반드시 연속적으로 놓 아야 한다.모든 작성 자 정 보 는 최종 HTML 코드 의 단독 단락 에 함께 저 장 됩 니 다.
  
변수 문서 태그 변수 문 서 는 삽 입 된 HTML 과@see 참조 만 포함 할 수 있 습 니 다.
방법 문서 표 시 는 HTML 과@see 참조 외 에 도 매개 변수,반환 값,이례 적 인 문서 표 시 를 사용 할 수 있 습 니 다.
@param 형식 은 다음 과 같 습 니 다.@param 매개 변수 이름 은 그 중에서'매개 변수 이름'은 매개 변수 목록 에 있 는 식별 자 를 말 합 니 다.'설명'은 후속 줄 로 이 어 질 수 있 는 설명 문 자 를 대표 합 니 다.새 문서 표 시 를 만나면 이전 설명 이 끝났다 고 생각 합 니 다.임의의 수량의 설명 을 사용 할 수 있 습 니 다.매개 매개 변 수 는 하나 입 니 다.
  
@return 형식 은 다음 과 같 습 니 다.@return 은 그 중에서'설명'은 반환 값 의 의 미 를 말 하 며 뒤의 줄 로 이 어 질 수 있 습 니 다.
  
@exception 의'이상'(Exception)에 대한 상세 한 상황 입 니 다.하나의 방법 을 호출 할 때,비록 하나의 이상 대상 만 나타 나 지만,일부 특수 한 방법 은 임의의 수량 과 서로 다른 유형의 이상 을 발생 시 킬 수 있다.모든 이상 은 설명 이 필요 하 다.이상 태그 의 형식 은 다음 과 같 습 니 다.@exception 의 전체 유형 은 그 중에서'전체 유형'은 위반 류 의 이름 을 명확 하 게 지정 하여 다른 곳 에서 정의 할 수 있 습 니 다.'설명'은 왜 이 이상 이 방법 호출 에 나타 나 는 지 설명 한다.
  
@deprecated 이 표 시 는 일부 오래된 기능 이 개 선 된 새로운 기능 으로 대체 되 었 음 을 지적 하 는 데 사 용 됩 니 다.이 태그 의 역할 은 사용자 가 특정한 기능 을 더 이상 사용 하지 않 아 도 된다 는 것 이다.왜냐하면 앞으로 개편 할 때 이 기능 을 버 릴 수 있 기 때문이다.하나의 방법 을@deprecated 로 표시 하면 이 방법 을 사용 할 때 컴 파일 러 의 경 고 를 받 습 니 다.
  
문서 예제 아래 는 우리 의 첫 번 째 자바 프로그램 입 니 다.단지 완전한 문서 주석 이 추가 되 었 을 뿐 입 니 다.
//: object/HelloDate.java 
import java.util.*; 
/** The first Thinking in Java example program. 
* Displays a string and today’s date. 
* @author Bruce Eckel 
* @author www.MindView.net 
* @version 4.0 
*/ 
public class HelloDate { 
/** Entry point to class & application. 
* @param args array of string arguments 
* @throws exceptions No exceptions thrown 
*/ 
public static void main(String[] args) { 
System.out.println("Hello, it’s: "); 
System.out.println(new Date()); 
} 
} /* Output: (55% match) 
Hello, it’s: 
Wed Oct 05 14:39:36 MDT 2005