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

Program / 글쓴이

저는 서명 만 다른 동일한 이름의 메서드를 많이 사용하는 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에 대한 확장? 아니면 내가 놓친 것이 지원되지 않는 이유가 있습니까?

답변

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

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

답변

“가장 완전한”메서드 (이 경우 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 );

답변

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

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

답변

가능하면 문서를 인터페이스에 넣으십시오. 인터페이스를 구현하는 클래스는 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을 가질 수 있으므로 더 쉽고 깔끔한 방법이 될 수 있습니다.

답변