API 도구는 API(유형, 메소드, 필드 등)에 추가된 새 요소에서 @since Javadoc 태그의 관리를 지원합니다.
새 API 요는 API 패키지에 추가된 새 유형, API 유형에 추가된 새 유형,API 유형에 추가된 새 메소드 또는 API 유형에 추가된 새 필드일 수 있습니다.
메소드 추가는 특수한 케이스로, 메소드 추가가 메소드를 유형에 추가하거나 상위 클래스 메소드를 대체하거나 상위 인터페이스 메소드를 구현하거나 기존 메소드의 서명을 변경하는 것이 될 수 있습니다.
참고: @since 태그 정보는 구현 또는 서브 클래싱(sub-classing)을 통해 전파되지 않습니다. API에 추가되는 각 요소는
자체적인 @since 태그와 버전 정보를 갖습니다.
도구는 @since 태그에 대해 다음과 같은 유효성 검증을 수행합니다.
@since 태그 관리를 위한 환경 설정은
플러그인 개발 > API 오류/경고 환경 설정 페이지에서 변경할 수 있습니다.
도구는 @since 태그가 있는지 확인하기 위해 발견되는 모든 새 API 요소를 검사합니다.
새 요소에 @since 태그가 없는 경우 태그가 필요하다는 플래그가 표시되며 태그의 버전을 제안받습니다.
새 태그에 제안되는 버전은 번들의 현재 버전이며 단, 번들 버전도 업데이트해야 하는 긴급 API 변경의 경우는 예외입니다.
번들 버전도 업데이트해야 하는 경우 누락된 @since 태그에 제안되는 버전은 제안된 번들 버전과 동일합니다.
다음 예제를 고려해 보십시오. 버전 1.0.0인 번들 A와, 메소드 method m1()을 포함하는 A의 버전 1.1.0에 클래스 C가 추가되었습니다.
@since 태그 문제점을 보고하고 @since 1.1을 m2()에 배치하도록 제안합니다. @since 태그 문제점을 보고하고
m2()에 새로운 @since 2.0 태그를 배치하도록 제안합니다. 여기서 2.0.0은 제안된 새 번들 버전입니다.
올바로 형식화되었는지 확인하기 위해 새 요소의 @since 태그에 대해 일관성을 검사합니다. API 도구는
모든 @since 태그가 다음과 같은 일반 형식을 취하는지 검사합니다.
[@since] [pre-amble] [2 part version] [post-amble]
다음과 같은 @since 태그 예제를 고려해 보십시오.
@since A 1 added m2(): 버전에 두 번째 세그먼트가 누락되었으므로 형식 오류로 플래그됩니다. @since: 버전 정보가 없으므로 형식 오류로 플래그됩니다. @since A: 버전 정보가 없으므로 플래그됩니다. @since 1.0.0: 버전의 세그먼트가 너무 많으므로 플래그됩니다. @since A 1.0 added m2(): 플래그되지 않습니다.
또한 새 요소의 @since 태그에 대해서는 유효성 검사도 수행합니다. 태그의 버전 정보가
번들의 버전과 일치하면 @since 태그는 올바른 것으로 간주됩니다.
버전 1.0.0인 번들 A의 API 클래스에 새 메소드 m2()를 추가한 다음 예제를 고려해 보십시오.
@since A 1.0 added method m2(): 올바른 것으로 간주됩니다. @since A 2.0 added method m2(): 번들 A의 버전이 1.0.0이므로 올바르지 않습니다. @since A 0.1 added method m2(): 번들 A의 버전이 1.0.0이므로 올바르지 않습니다.