javadocs의 코드 예제를 최신으로 유지하는 방법

잘 알려진 기본 문자열 메트릭의 구현을 제공하는 작은 라이브러리에서 작업하고 있습니다. 대부분 내 자신의 교육을 위해. 약간의 여가 시간이있을 때마다 개발이 이루어집니다.

이로 인해 대부분의 프로세스를 자동화하여 너무 많은 노력을 기울이지 않고도 작업 할 때마다 버전을 릴리스 할 수 있습니다. 그러나 Java doc을 유지하는 것은 예제를 포함하므로 여전히 부담입니다.

API가 발전함에 따라 수동으로 각 예제를 반복해서 확인해야합니다. 더 좋은 방법이 있습니까?

문서와 예제를 별도의 프로젝트 (예 : Caliper Tutorial ) 로 옮기는 것을 고려 하여 일반 코드와 함께 리팩터링하고 컴파일 할 수 있습니다. 그러나 이것은 문서를 클래스에서 멀어지게합니다.

그래 나는 케이크를 먹고 싶어요. :디

 * <h2>Tokenization</h2>
 * 
 * Tokenization cuts up a string into tokens e.g.
 * <code>chilperic ii son of childeric ii</code> is tokenized into
 * <code>[chilperic, ii, son, of,
 * childeric, ii]</code>. Tokenization can also be done repeatedly by tokenizing
 * the individual tokens e.g.
 * <code>[ch,hi,il,il,lp,pe,er,ri,ic, ii, so,on, of, ch,hi,il,ld,de,er,ri,ic, ii]</code>
 * <p>
 * 
 * <pre>
 * <code>
 * {@code
 *  return new StringMetricBuilder()
 *          .with(new SimonWhite<String>())
 *          .tokenize(new Whitespace())
 *          .tokenize(new QGram(2))
 *          .build();
 * }
 * </code>
 * </pre>
 * 
 * <p>

위의 경우 너무 추상적입니다. 이 문서는 샘플입니다. 현재 효과적인 Java가 조언하는대로 정적 생성자를 추가 Tokenizers.createQGram(2)하고 있습니다. 예 를 들어 생성자 메서드를 감가 상각합니다. 이런 식으로 할 때마다 위의 예제 코드를 업데이트하고 여전히 작동하는지 확인해야합니다.

문서에 이러한 예를 포함하는 것이 얼마나 많은 '요구 사항'에 따라 귀하의 질문에 대답하지 못할 수도 있습니다.

아마도 당신은 다른 각도에서 할 수 있습니다 : JUnit 테스트에서 예제를 제공하십시오. (com.examples와 같은 패키지 일 수도 있습니다.) 주석의 코드 문제는 IDE에서 대부분 무시할 것입니다. 그러나 IDE는 JUnit 테스트에서 코드의 유효성을 검사합니다. 이렇게하면 코드 예제가 '올바른'지 확인할 수 있습니다. 테스트가 컴파일되지 않았거나 업데이트하지 않은 경우 테스트가 실패합니다.

Javadocs가있는 마법사는 아니지만 소스 파일의 문서를 예제 코드가있는 JUnit 파일에 링크하는 방법이있을 수 있습니다. 그래도 어디서부터 시작 해야할지 모르겠습니다. 엉뚱한 인터넷 검색 창에 @see태그가 표시되었습니다 . 프로젝트에서 테스트했지만 생성 후 실제 javadoc에서 테스트하지 않았습니다.

이것은 분명히 약간의 연구가 필요하지만 코드 예제가 실제로 컴파일된다면 장기적으로 더 나아질 것이라고 생각합니다.

간단한 목표로 JUnit 예제를 실행할 때 코드 범위를 추가 할 수도 있습니다. 이렇게하면 예제에서 다루는 코드베이스의 양을 한 눈에 알 수 있습니다.