Javadoc의 내부/외부 메소드 구별

Question

자바로 라이브러리를 작성하고 있습니다. 구현을 Java 패키지로 나누어 복잡성을 관리하는 데 도움이됩니다. 하나의 패키지에만 라이브러리의 클라이언트가 볼 수있는 클래스가 들어 있습니다. 그러나 public 메소드 만이 라이브러리의 다른 패키지에서 사용할 수 있도록 패키지 외부에서 볼 수 있기 때문에 다음 중 하나를 수행해야합니다.

(1) 외부에서 볼 수있는 인터페이스와 팩토리 메소드 패키지를 구현하여 this SO answer에 설명 된대로 해당 인터페이스의 구현을 별도의 패키지에 넣습니다. 예 : external.MyInterface 및 internal.MyInterfaceImpl. 나는이 성가신 것을 발견한다.

(2) 외부 패키지에 내부 및 외부 메서드 public을 만들고 내부 메서드에 Javadoc 태그를 첨부하여 수동으로 (오류가 발생하기 쉬운) 또는 일종의 Javadoc 프리 프로세서 또는 포스트 프로세서.

(3)이 목적을 위해 Javadoc이 제공하는 메커니즘 (이상적으로 Javadoc 태그)을 사용하십시오.

접근 방식이 무엇이든간에, 내가 정말로 신경을 쓰는 것은 외부 API에 대한 Javadocs를 자동으로 생성하는 일관된 방법입니다. 이것을하기위한 표준 방법이 있습니까? 목적을위한 도구?

Answer 1

다른 곳에서 these two answers을 찾았습니다. 한 가지 방법은 사용자 정의 Javadoc 주석을 작성하고 Javadoc을 생성하기 전에 Ant 태스크가 deprecated으로 주석을 대체하도록하는 것입니다. 더 쉬운 방법은 Doxygen의 조건부 포함을 사용하는 것입니다.

저는 Javadoc이 붙어 있지 않아서 Doxygen을 사용할 수 있습니다. 그러나 현재 Doxygen을 살펴보면 Javadoc과 크게 다르므로 학습 곡선의 가치가 있는지 또는 외부 API를 생성 할 수있는 선례를 세울 가치가 있는지 확신 할 수 없습니다.

내가 빌드 할 위치에있을 때 다음에 시도 할 또 다른 해결책은 다음과 같습니다. 내부 전용 소스 파일 부분을 분리하고 외부 패키지의 소스 파일을 복제하는 도구를 작성하면서 내부 전용으로 구분 된 파일 부분을 제거한 다음 Javadoc을 생성 된 소스에서 실행합니다. Javadoc이 링커를 행복하게 해줄 필요가없는 한, 이것은 작동 할 것이다.

내 질문을 계속 지킬 가치가 있는지 알 수 없습니다. 다른 사람들이 내가 생각했던대로 대답을 찾도록 도울 수 있습니다. 그렇더라도 아직 아무도 훌륭한 솔루션을 제시하지 못했습니다.

Answer 2

내가 수년 동안 사용해온 대안은이 블로그에 제공된 공개 도메인 코드 인 Implementing @exclude using Dynamic Proxies을 사용하여 @exclude 태그를 추가하는 것입니다.

는 자바 독에 @exclude 태그를 추가, Javadoc의 출력에서 ​​자바 요소 (속성, 메소드, 생성자, 클래스, 내부 클래스 또는 패키지)를 제외하려면 :

public class MyClass { 
    /** 
    * This is my internal attribute, javadoc not exposed. 
    * @exclude 
    */ 
    protected String myInternalAttribute; 

    /** 
    * This is my external attribute, javadoc is exposed. 
    */ 
    protected String myExternalAttribute; 

    /** 
    * This is my internal method, javadoc not exposed. 
    * @exclude 
    */ 
    public void myInternalMethod() { } 

    /** 
    * This is my external method, javadoc is exposed. 
    */ 
    public void myExternalMethod() { } 
}