오버로드 된 메소드에 대한 Javadoc 재사용

Question 1

저는 서명 만 다른 동일한 이름의 메서드를 많이 사용하는 API를 개발 중입니다. 사용자가 지정하지 않으려는 경우 기본적으로 다양한 값을 초기화한다는 점을 제외하면 모두 동일한 작업을 수행합니다. 이해하기 쉬운 예로서

public interface Forest
{
  public Tree addTree();

  public Tree addTree(int amountOfLeaves);

  public Tree addTree(int amountOfLeaves, Fruit fruitType);

  public Tree addTree(int amountOfLeaves, int height);

  public Tree addTree(int amountOfLeaves, Fruit fruitType, int height);
}

이러한 모든 방법으로 수행되는 필수 작업은 동일합니다. 숲에 나무가 심어 져 있습니다. API 사용자가 이러한 모든 메서드에 대해 트리를 추가하는 데 필요한 많은 중요한 사항이 있습니다.

이상적으로는 모든 메소드에서 사용되는 하나의 Javadoc 블록을 작성하고 싶습니다.

  /**
   * Plants a new tree in the forest. Please note that it may take
   * up to 30 years for the tree to be fully grown.
   *
   * @param amountOfLeaves desired amount of leaves. Actual amount of
   * leaves at maturity may differ by up to 10%.
   * @param fruitType the desired type of fruit to be grown. No warranties
   * are given with respect to flavour.
   * @param height desired hight in centimeters. Actual hight may differ by
   * up to 15%.
   */

내 상상으로는 도구가 각 메서드에 적용 할 @params를 마술처럼 선택하여 모든 메서드에 대한 좋은 문서를 한 번에 생성 할 수 있습니다.

Javadoc을 사용하면 올바르게 이해하면 기본적으로 동일한 javadoc 블록을 5 번 복사 및 붙여 넣기 만하면됩니다. 각 메서드에 대한 매개 변수 목록은 약간만 다릅니다. 이것은 나에게 번거로운 것처럼 들리며 유지 관리도 어렵습니다.

그 주위에 방법이 있습니까? 이런 종류의 지원이있는 javadoc에 대한 확장? 아니면 내가 놓친 것이 지원되지 않는 이유가 있습니까?

Question 2

나는 어떤 지원도 모르지만, 가장 많은 인수를 가진 메소드를 완전히 javadoc하고 다른 javadoc에서 그렇게 참조합니다. 나는 그것이 충분히 명확하고 중복을 피한다고 생각합니다.

/**
 * {@code fruitType} defaults to {@link FruitType#Banana}.
 *
 * @see Forest#addTree(int, Fruit, int)
 */

Question 3

"가장 완전한"메서드 (이 경우 addTree(int,Fruit,int))를 문서화 한 다음 다른 메서드에 대한 JavaDoc에서이 메서드를 참조하고 제공되지 않은 인수에 대해 사용되는 기본값을 설명합니다.

/**
 * Works just like {@link ThisClass#myPow(double,double)} except the exponent is always 
 * presumed to be 2. 
 *
 * @see ThisClass#myPow(double,double)
 */
 static double myPow( double base );

Question 4

JDK9 소스 코드조차도 다음과 같이 많은 양의 문서를 복사하여 붙여 넣기 때문에 좋은 표준 방법이 없을 가능성이 높습니다.

4 줄의 주석이 반복됩니다. 비 건조 함.

Question 5

가능하면 문서를 인터페이스에 넣으십시오. 인터페이스를 구현하는 클래스는 javadoc을 상속합니다.

interface X(){
 /** does fooish things */
 void foo();
}

class Ax implements X{ //automatically inherits the Javadoc of "X"
 @Override 
 public void foo(){/*...*/} 
}

문서를 상속하고 문서에 자신의 내용을 추가하려면 {@inheritDoc}을 사용할 수 있습니다.

class Bx implements X{
 /**
  * {@inheritDoc}
  * May fail with a RuntimeException, if the machine is too foo to be true.
  */
 @Override 
 public void foo(){/*...*/}
}

참조 : http://docs.oracle.com/javase/1.5.0/docs/tooldocs/windows/javadoc.html#inheritingcomments

이제 내가 이해했듯이 이것은 정확히 원하는 것이 아닙니다 (동일한 클래스 / 인터페이스의 메서드 사이에서 반복을 피하고 싶습니다). 이를 위해 다른 사람이 설명한대로 @see 또는 @link를 사용하거나 디자인에 대해 생각할 수 있습니다. 메서드 오버로드를 피하고 대신 매개 변수 개체와 함께 단일 메서드를 사용하고 싶을 수 있습니다.

public Tree addTree(TreeParams p);

다음과 같이 사용하려면 :

forest.addTree(new TreeParams().with(Fruits.APPLE).withLeaves(1500).withHeight(5));

여기에서이 카피 뮤 테이터 패턴을 살펴볼 수 있습니다.

https://brixomatic.wordpress.com/2010/03/10/dealing-with-immutability-and-long-constructors-in-a-fluent-way/

매개 변수 조합의 양에 따라 Params-Class가 기본값을 캡처하고 각 매개 변수에 대한 javadoc을 가질 수 있으므로 더 쉽고 깔끔한 방법이 될 수 있습니다.