Javadoc 재사용 및 오버로드 된 메소드

Javadoc 재사용 및 오버로드 된 메소드

---

서명 만 다른 동일한 이름의 메서드를 많이 사용하는 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 소스 코드조차도 다음과 같이 많은 양의 문서를 복사하여 붙여 넣기 때문에 좋은 표준 방법이 없을 가능성이 높습니다.

• http://hg.openjdk.java.net/jdk9/jdk9/jdk/file/07175dc5b2da/src/java.desktop/share/classes/java/awt/Container.java#l417
• http://hg.openjdk.java.net/jdk9/jdk9/jdk/file/07175dc5b2da/src/java.desktop/share/classes/java/awt/Container.java#l464

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

Now as I understood, this is not exactly what you want (you want to avoid repetitions among the methods in the same class/interface). For this you can use @see or @link, as described by others, or you might think about your design. Maybe you'd like to avoid overloading the method and use a single method with a parameter object instead, like so:

public Tree addTree(TreeParams p);

To be used like this:

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

You might like to have a look at this copy-mutator pattern here:

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

Depending on the amount of parameter combinations this could be the easier and cleaner way, since the Params-Class could capture the defaults and have a javadoc for each parameter.

참고URL : https://stackoverflow.com/questions/2558695/javadoc-reuse-for-and-overloaded-methods