javadoc : @version and @since

Question

@version and @since을 클래스의 일부로 포함해야하는 이유가 있습니까?

그들은 상호 배타적 인 것처럼 보입니다.

또한 %I% and %G%의 의미는 무엇이며 어떻게 설정하고 사용합니까?

@version %I%, %G% 

감사

Answer 1

@version 태그는 해당 릴리스 나 파일의 최신 버전이어야합니다. %I%, %G% 구문은 소스 제어 소프트웨어가 파일의 현재 버전과 파일을 체크 아웃 한 날짜로 바꿀 매크로입니다.

@since 태그는 메소드, 클래스 등을 추가 한 버전을 정의하는 데 사용해야합니다. 이는 다른 버전의 개발자가 특정 버전의 패키지에 대해 메소드를 실행할 때만 기대해야한다는 힌트입니다. 다른 사람들이 사용하기 위해 만든 라이브러리로 코드를 출하한다면 이러한 문서의 핵심 부분을 고려할 것입니다.

Answer 2

나는 그들이 상호 배타적 표시되지 않습니다. 하나는 버전을 정의하는 데 사용되고 다른 하나는 메소드가있을 때부터 설명하기 위해 사용됩니다. 예를 들면 다음과 같습니다.

/** 
* Does Whatever 
* @version 1.2.3 
* @since 1.2.0 
* 
*/ 
public void myMethod() { 
    // ....... 
} 

언급 한 문자는 독점적 인 것으로 보이며 어쨌든 의미가 무엇인지 알지 못합니다.

Answer 3

@version 모든 편집 기록 될 것입니다. [1.3.21]

@since는 릴리스 버전 등이 인터페이스 또는 지원되기 때문에 의미입니다 [1.3] Yuval 교수 아담은 재미있다, 그러나 이것은 표준 아닙니다 , 자바 의사의 목적은 모두 이해할 수있다.

Answer 4

오라클의 문서 How to Write Doc Comments for the Javadoc Tool에서 잘 설명되어 있습니다.

@version

... 클래스 및 인터페이스만을.

Java 소프트웨어에서 우리는 SCCS 버전에 @version을 사용합니다. 자세한 내용은 "man sccs-get"을 참조하십시오. 합의는 다음과 같은 것 같다 :

퍼센트의 I의 %는 편집 및

%의 G의 %는 날짜 mm /있는 파일을하고 delget 때마다 증가 도착 일/년

당신이 파일을 생성

, % I %는 1.1로 설정됩니다. 편집 및 삭제할 때 1.2로 증가합니다.

일부 개발자는 너무 혼동 스럽다면 % G % 날짜를 생략합니다. 예를 들어, 3/4/96은 3 월 4 일에 생산할 % G %가 다음과 같이 해석합니다. 4 월 3 일을 의미하는 미국 밖의 사람들. 일부 개발자는 (하루에 여러 번의 체크인으로 인해) 더 세밀한 해결을 원할 때만 % U % 시간을 포함합니다.

ISO 8601 및 다른 곳에서 제안 된대로 (예 : http://www.cl.cam.ac.uk/~mgk25/iso-time.html) yerey-mm-dd와 같이 연도가 가장 명확한 날짜 형식은 년으로 시작하는 형식이어야하지만 그 향상은 SCCS. 자바 이름 (구현과 다른 경우) API 사양에 추가 될 때 @since

제품 버전을 지정합니다. 예를 들어, 패키지, 클래스, 인터페이스 또는 멤버는, Java 2 Platform, Standard Edition, 버전 1.2의 API 사양에 추가 된 경우는 사용

/** 
* @since 1.2 
*/ 

는 "때문에 표시 도크 렛 Javadoc의 표준 "문자열 인수를 텍스트로 갖는 부제목. 이 소제목은 소스 문서 주석에 @since 태그가 나타나는 곳에 해당하는 위치에서만 생성 된 텍스트에 나타납니다 (Javadoc 도구는 계층 구조 아래로 확산시키지 않습니다).

(컨벤션 번 "@since의 JDK1.2"했지만이 자바 플랫폼의 사양이기 때문에,하지 특히 ​​오라클 JDK 나 SDK로, 우리는 "JDK를"떨어졌다.)

때 패키지가 소개되면 패키지 설명 및 각 클래스에서 @since 태그를 지정하십시오. (각 클래스에 @since 태그를 추가하는 것은 기술적으로는 필요하지 않지만, 소스 코드에서 더 많은 가시성을 가능하게하는 우리의 관례입니다.) 오버라이드 태그가없는 경우 @since 태그의 값은 각 패키지의 클래스에 적용되며 회원.

클래스 (또는 인터페이스)가 도입되면 클래스 설명에 @since 태그 하나를 지정하고 멤버에는 @since 태그를 지정하지 마십시오. @since 태그는 클래스보다 이후 버전에 추가 된 멤버에게만 추가하십시오. 이렇게하면 @since 태그의 수가 최소화됩니다.

이후 릴리스에서 멤버가 protected에서 public으로 변경되면 @since 태그는 서브 클래스가 아닌 모든 호출자가 사용할 수있게 되어도 변경되지 않습니다.