@deprecated와 같이 실험적이거나 불완전한 API를 문서화하는 방법은 무엇입니까?

메소드 또는 API가 코드베이스에 있지만 구현이 완료되지 않았거나 변경 될 가능성이 있으므로 사용해서는 안된다는 의미로 "deprecate"와 유사하지만 좋은 용어가 있습니까? (예, 그 방법은 공개되어서는 안됩니다. yada yada yada. 나는 상황을 만들지 않았으며 최선을 다하려고 노력하고 있습니다.)

사람들은 무엇을 제안합니까? 실험적이고 불완전한 다른 것?

여전히 유동적 인이 API에 대한 javadoc 문서를 작성하는 경우 @deprecated 태그를 사용해야합니까 아니면 더 나은 규칙이 있습니까? 나에게 @deprecated는이 API가 오래되었고 새로운 선호 메커니즘이 있음을 의미합니다. 내 상황에는 대안이 없지만 API의 일부 메소드가 완료되지 않았으므로 사용해서는 안됩니다. 이 시점에서 나는 그것들을 비공개로 만들 수는 없지만 문서에 명확한 경고를하고 싶습니다.

적절한 용어는 인큐베이터 일 가능성 이 높습니다 . 이것은 Google 및 Apache에서 사용되는 용어입니다 .

• google-web-toolkit-incubator

  Google Web Toolkit 용 위젯 및 라이브러리의 공식 인큐베이터 ...

• 아파치 인큐베이터

  ... 아파치 소프트웨어 파운데이션 프로젝트를 본격화하기위한 오픈 소스 프로젝트의 게이트웨이 ...

위에서 언급 한 프로젝트를 자세히 살펴보면 "실험"API (예 : GWT)가 "전용"패키지 이름을 갖는 경향이 있음을 알 수 있습니다 com.google.gwt.gen2. 이것은 영구적 인 공공 소비를 목적으로하는 미래의 "최종화 된"API를 오염시키지 않기위한 것입니다.

"공개 API는, 다이아몬드처럼, 당신은 그것을 잘 그래서 당신의 최고의 ...주고받을 수있는 하나의 기회가 있습니다. 영원히" (여호수아 블로흐는 어떻게 디자인 할 수있는 좋은 API를하고 중요한 이유 )

나는 @deprecated순전히 실용적인 이유로 사용할 것 입니다.

하지만 @deprecated당신이 좋아하는 것이 정확한 의미를 전달하지 않습니다, 그것은 상당한 이점이있다 : 자바 컴파일러가 내장되어 그것을 지원. -deprecation플래그로 컴파일 하면 더 이상 사용되지 않는 메소드를 대체하는 모든 위치를 찾을 수 있으므로 사용자가 의심스러운 코드를 매우 빨리 찾을 수 있습니다. @deprecatedJavadoc 태그를 사용 하여 문서를 읽고 싶어하는 사람에게 실제로 어떤 일이 일어나고 있는지 설명 할 수 있습니다 . 여기서는 사용자에게 API가 실험적이며 자신의 위험에 따라 사용해야한다는 등의 조치를 취할 수 있습니다.

실험적이거나 불완전한 기능은 공개 API에서 아무 관련이 없기 때문에 다른 API에서는 이와 같은 것을 본 적이 없습니다.

선택의 여지가 없으므로 API의 일부가 변경 될 수 있음을 명확하게 표시하십시오.